AsyncSemaphore (Tascalate Concurrent 0.9.6 API)

All Known Implementing Classes:

DefaultAsyncSemaphore
```
public interface AsyncSemaphore
```

Method Summary

All Methods Static Methods Instance Methods Abstract Methods Default Methods
Modifier and Type	Method and Description
`default Promise<Long>`	`acquire()` Acquires 1 permit from the semaphore as if by calling `acquire(long)` with an argument of 1.
`Promise<Long>`	`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`	`availablePermits()` Gets the number of currently available permits.
`static AsyncSemaphore`	`create(long permits, boolean fair)`
`long`	`drainPermits()` Acquires all permits that are immediately available.
`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
```
default Promise<Long> acquire()
```
    Acquires 1 permit from the semaphore as if by calling acquire(long) with an argument of 1.
    
    Returns:
    
    a Promise which will complete when 1 permit has been successfully acquired
    
    See Also:
    
    acquire(long)
  - acquire
```
Promise<Long> 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 Promise 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
```
default void release()
```
    Releases 1 permit from the semaphore as if by calling release(long) with an argument of 1.
    
    See Also:
    
    release(long)
  - 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
```
default boolean tryAcquire()
```
    Attempts to acquire 1 permit from the semaphore as if by calling tryAcquire(long) with an argument of 1.
    
    Returns:
    
    true if the single request permit is available, and has been immediately acquired
    
    See Also:
    
    tryAcquire(long)
  - 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 if 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
  - availablePermits
```
long availablePermits()
```
    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
  - create
```
static AsyncSemaphore create(long permits,
                             boolean fair)
```

Interface AsyncSemaphore

Method Summary

Method Detail

acquire

acquire

release

release

tryAcquire

tryAcquire

drainPermits

availablePermits

getQueueLength

create