AsyncSemaphore
public class FairAsyncSemaphore extends Object implements AsyncSemaphore
AsyncSemaphore
implementation which is strictly fair: if the permits requested by an
acquire(long)
cannot be fulfilled immediately, all subsequent acquires must wait for
their predecessor to be fulfilled. This is the same behavior as a synchronous
Semaphore
with the fairness parameter set to true.
The internal permit representation may employ fewer than 64 bits to store the (possibly negative)
permit count; as a result, the bounds of available permits are restricted. Methods which take a
number of permits as an argument are generally restricted to a maximum value of
MAX_PERMITS
. Similarly, the initial permit value provided to the
constructor must be at least as great as the defined MIN_PERMITS
value
Modifier and Type | Field | Description |
---|---|---|
static long |
MAX_PERMITS |
|
static long |
MIN_PERMITS |
The greatest deficit of permits with which this semaphore implementation can be initialized.
|
Constructor | Description |
---|---|
FairAsyncSemaphore(long initialPermits) |
Creates a new asynchronous semaphore with the given initial number of permits.
|
Modifier and Type | Method | Description |
---|---|---|
CompletionStage<Void> |
acquire(long permits) |
Acquires the given number of permits using an acquisition-ordered fair queuing policy, i.e.
|
long |
drainPermits() |
Acquires all permits that are immediately available.
|
long |
getAvailablePermits() |
Gets the number of currently available permits.
|
int |
getQueueLength() |
Gets the number of unfulfilled acquisitions waiting on this semaphore's permits.
|
void |
release(long permits) |
Releases the given number of permits to the semaphore.
|
String |
toString() |
|
boolean |
tryAcquire(long permits) |
Attempts to acquire the given number of permits if they are immediately available.
|
acquire, release, tryAcquire
public static final long MIN_PERMITS
public static final long MAX_PERMITS
acquired
or released
with a single
operation.public FairAsyncSemaphore(long initialPermits)
releases
before acquisitions
initialPermits
- The initial number of permits available in the semaphore. This value must
be within the interval [MIN_PERMITS
, MAX_PERMITS
]public final CompletionStage<Void> acquire(long permits)
It is possible to request an acquisition of 0
permits, which in this implementation has
a specific meaning: if there are no queued waiters and zero or more permits available, the
acquisition will complete immediately; if there are queued waiters or a permit deficit, the
zero-acquisition will complete after the last queued waiter (at the time of acquisition) is
released. No permits will be reserved by the zero-acquisition in either of these cases. This
behavior can be used to wait for pending acquisitions to complete, without affecting the permit
count.
acquire
in interface AsyncSemaphore
permits
- The number of permits to acquire. This value must be non-negative and no greater
than MAX_PERMITS
CompletionStage
which will be completed when all permits
have been
acquiredAsyncSemaphore.acquire(long)
public final void release(long permits)
AsyncSemaphore
If there are unfulfilled acquires pending, this method will release permits to the waiting acquisitions based on the implementation's release and acquire policies. Consequently, this method may complete a number of waiting stages and execute the corresponding observers.
release
in interface AsyncSemaphore
permits
- The number of permits to release. This value must be non-negative and no greater
than MAX_PERMITS
public final boolean tryAcquire(long permits)
Note that this differs from the behavior of
Semaphore.tryAcquire(int)
with a fairness policy. This method will
not barge ahead of other waiters.
As with acquire(long)
, it is possible to tryAcquire
with zero permits. This
will return true
iff there are no queued waiters and zero or more permits are available
in the semaphore.
tryAcquire
in interface AsyncSemaphore
permits
- The number of permits to acquire. This value must be non-negative and no greater
than MAX_PERMITS
AsyncSemaphore.tryAcquire(long)
public final long drainPermits()
AsyncSemaphore
After this call -- provided there are no intermediate releases
-- any
attempt to acquire
will queue and any tryAcquire
will fail.
drainPermits
in interface AsyncSemaphore
public final long getAvailablePermits()
AsyncSemaphore
The bounds of the returned value are not defined; an implementation may, for example, choose to represent waiting acquisitions as holding negative permits, and thus the value returned by this method could be negative. Furthermore, a positive number of permits returned by this method may not indicate that such permits are acquirable, as the waiter-queue policy may prohibit fulfilling further acquisitions.
This value is produced on a best-effort basis, and should not be used for any control logic. Generally it is only useful in testing, debugging, or statistics purposes.
getAvailablePermits
in interface AsyncSemaphore
public final int getQueueLength()
AsyncSemaphore
This value is produced on a best-effort basis, and should not be used for any control logic. Generally it is only useful in testing, debugging, or statistics purposes.
getQueueLength
in interface AsyncSemaphore
Copyright © 2018. All rights reserved.