Package com.ibm.asyncutil.locks

Interface AsyncSemaphore

All Known Implementing Classes:

FairAsyncSemaphore

public interface AsyncSemaphore

An asynchronously acquirable counting semaphore

Implementations will specify whether their permit acquisition and release is fair or not; this interface does not define this requirement.

Method Summary

Modifier and Type	Method	Description
default CompletionStage<Void>	acquire()	Acquires 1 permit from the semaphore as if by calling acquire(long) with an argument of 1.
CompletionStage<Void>	acquire(long permits)	Acquires the given number of permits from the semaphore, returning a stage which will complete when all of the permits are exclusively acquired.
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.
default void	release()	Releases 1 permit from the semaphore as if by calling release(long) with an argument of 1.
void	release(long permits)	Releases the given number of permits to the semaphore.
default boolean	tryAcquire()	Attempts to acquire 1 permit from the semaphore as if by calling tryAcquire(long) with an argument of 1.
boolean	tryAcquire(long permits)	Attempts to acquire the given number of permits from the semaphore, returning a boolean indicating whether all of the permits were immediately available and have been exclusively acquired.

Method Detail

acquire

CompletionStage<Void> acquire(long permits)

Acquires the given number of permits from the semaphore, returning a stage which will complete when all of the permits are exclusively acquired. The stage may already be complete if the permits are available immediately.

If the permits are not available immediately, the acquisition will enter a queue and an incomplete stage will be returned. Semantics of the waiter queue, including ordering policies, are implementation specific and will be defined by the given implementing class. The returned stage will complete when sufficient permits have been released and assigned to this acquisition by the governing queue policy.

Parameters:

permits - A non-negative number of permits to acquire from the semaphore

Returns:

a CompletionStage which will be completed when all permits have been acquired

Throws:

IllegalArgumentException - if the requested permits are negative, or exceed any restrictions enforced by the given implementation

release

void release(long permits)

Releases the given number of permits to the semaphore.

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.

Parameters:

permits - A non-negative number of permits to release to the semaphore

Throws:

IllegalArgumentException - if the released permits are negative, or exceed any restrictions enforced by the given implementation

tryAcquire

boolean tryAcquire(long permits)

Attempts to acquire the given number of permits from the semaphore, returning a boolean indicating whether all of the permits were immediately available and have been exclusively acquired.

Implementations may define precise behavior of this method with respect to competing acquisitions, e.g. whether permits may be acquired while other acquisitions are waiting. This interface only requires that this method will succeed when the given permits are available and there are no other acquisitions queued.

Parameters:

permits - A non-negative number of permits to acquire from the semaphore

Returns:

true iff all of the requested permits are available, and have been immediately acquired

Throws:

IllegalArgumentException - if the requested permits are negative, or exceed any restrictions enforced by the given implementation

drainPermits

long drainPermits()

Acquires all permits that are immediately available.

After this call -- provided there are no intermediate releases -- any attempt to acquire will queue and any tryAcquire will fail.

Returns:

the number of permits that were available and have been drained

getAvailablePermits

long getAvailablePermits()

Gets the number of currently available permits.

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.

Returns:

the number of currently available permits

getQueueLength

int getQueueLength()

Gets the number of unfulfilled acquisitions waiting on this semaphore's permits.

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.

Returns:

the number of unfulfilled acquisitions waiting on this semaphore's permits

acquire

default CompletionStage<Void> acquire()

Acquires 1 permit from the semaphore as if by calling acquire(long) with an argument of 1.

Returns:

a CompletionStage which will complete when 1 permit has been successfully acquired

See Also:

acquire(long)

release

default void release()

Releases 1 permit from the semaphore as if by calling release(long) with an argument of 1.

See Also:

release(long)

tryAcquire

default boolean tryAcquire()

Attempts to acquire 1 permit from the semaphore as if by calling tryAcquire(long) with an argument of 1.

Returns:

true iff the single request permit is available, and has been immediately acquired

See Also:

tryAcquire(long)