| 93 |
|
* guarantees about the order in which threads acquire permits. In |
| 94 |
|
* particular, <em>barging</em> is permitted, that is, a thread |
| 95 |
|
* invoking {@link #acquire} can be allocated a permit ahead of a |
| 96 |
< |
* thread that has been waiting. When fairness is set true, the |
| 96 |
> |
* thread that has been waiting - logically the new thread places itself at |
| 97 |
> |
* the head of the queue of waiting threads. When fairness is set true, the |
| 98 |
|
* semaphore guarantees that threads invoking any of the {@link |
| 99 |
< |
* #acquire() acquire} methods are allocated permits in the order in |
| 99 |
> |
* #acquire() acquire} methods are selected to obtain permits in the order in |
| 100 |
|
* which their invocation of those methods was processed |
| 101 |
|
* (first-in-first-out; FIFO). Note that FIFO ordering necessarily |
| 102 |
|
* applies to specific internal points of execution within these |
| 103 |
|
* methods. So, it is possible for one thread to invoke |
| 104 |
|
* <tt>acquire</tt> before another, but reach the ordering point after |
| 105 |
|
* the other, and similarly upon return from the method. |
| 106 |
+ |
* Also note that the untimed {@link #tryAcquire() tryAcquire} methods do not |
| 107 |
+ |
* honor the fairness setting, but will take any permits that are |
| 108 |
+ |
* available. |
| 109 |
|
* |
| 110 |
|
* <p>Generally, semaphores used to control resource access should be |
| 111 |
|
* initialized as fair, to ensure that no thread is starved out from |
| 371 |
|
* Releases a permit, returning it to the semaphore. |
| 372 |
|
* <p>Releases a permit, increasing the number of available permits |
| 373 |
|
* by one. |
| 374 |
< |
* If any threads are blocking trying to acquire a permit, then one |
| 374 |
> |
* If any threads are trying to acquire a permit, then one |
| 375 |
|
* is selected and given the permit that was just released. |
| 376 |
< |
* That thread is re-enabled for thread scheduling purposes. |
| 376 |
> |
* That thread is (re)enabled for thread scheduling purposes. |
| 377 |
|
* <p>There is no requirement that a thread that releases a permit must |
| 378 |
|
* have acquired that permit by calling {@link #acquire}. |
| 379 |
|
* Correct usage of a semaphore is established by programming convention |
| 412 |
|
* then {@link InterruptedException} is thrown and the current thread's |
| 413 |
|
* interrupted status is cleared. |
| 414 |
|
* Any permits that were to be assigned to this thread are instead |
| 415 |
< |
* assigned to the next waiting thread(s), as if |
| 416 |
< |
* they had been made available by a call to {@link #release()}. |
| 415 |
> |
* assigned to other threads trying to acquire permits, as if |
| 416 |
> |
* permits had been made available by a call to {@link #release()}. |
| 417 |
|
* |
| 418 |
|
* @param permits the number of permits to acquire |
| 419 |
|
* |
| 517 |
|
* then {@link InterruptedException} is thrown and the current thread's |
| 518 |
|
* interrupted status is cleared. |
| 519 |
|
* Any permits that were to be assigned to this thread, are instead |
| 520 |
< |
* assigned to the next waiting thread(s), as if |
| 521 |
< |
* they had been made available by a call to {@link #release()}. |
| 520 |
> |
* assigned to other threads trying to acquire permits, as if |
| 521 |
> |
* the permits had been made available by a call to {@link #release()}. |
| 522 |
|
* |
| 523 |
|
* <p>If the specified waiting time elapses then the value <tt>false</tt> |
| 524 |
|
* is returned. |
| 525 |
|
* If the time is |
| 526 |
|
* less than or equal to zero, the method will not wait at all. |
| 527 |
|
* Any permits that were to be assigned to this thread, are instead |
| 528 |
< |
* assigned to the next waiting thread(s), as if |
| 529 |
< |
* they had been made available by a call to {@link #release()}. |
| 528 |
> |
* assigned to other threads trying to acquire permits, as if |
| 529 |
> |
* the permits had been made available by a call to {@link #release()}. |
| 530 |
|
* |
| 531 |
|
* @param permits the number of permits to acquire |
| 532 |
|
* @param timeout the maximum time to wait for the permits |
| 550 |
|
* Releases the given number of permits, returning them to the semaphore. |
| 551 |
|
* <p>Releases the given number of permits, increasing the number of |
| 552 |
|
* available permits by that amount. |
| 553 |
< |
* If any threads are blocking trying to acquire permits, then the |
| 550 |
< |
* one that has been waiting the longest |
| 553 |
> |
* If any threads are trying to acquire permits, then one |
| 554 |
|
* is selected and given the permits that were just released. |
| 555 |
|
* If the number of available permits satisfies that thread's request |
| 556 |
< |
* then that thread is re-enabled for thread scheduling purposes; otherwise |
| 557 |
< |
* the thread continues to wait. If there are still permits available |
| 558 |
< |
* after the first thread's request has been satisfied, then those permits |
| 559 |
< |
* are assigned to the next waiting thread. If it is satisfied then it is |
| 560 |
< |
* re-enabled for thread scheduling purposes. This continues until there |
| 558 |
< |
* are insufficient permits to satisfy the next waiting thread, or there |
| 559 |
< |
* are no more waiting threads. |
| 556 |
> |
* then that thread is (re)enabled for thread scheduling purposes; |
| 557 |
> |
* otherwise the thread will wait until sufficient permits are available. |
| 558 |
> |
* If there are still permits available |
| 559 |
> |
* after this thread's request has been satisfied, then those permits |
| 560 |
> |
* are assigned in turn to other threads trying to acquire permits. |
| 561 |
|
* |
| 562 |
|
* <p>There is no requirement that a thread that releases a permit must |
| 563 |
|
* have acquired that permit by calling {@link Semaphore#acquire acquire}. |
