ISemaphore (Hazelcast API

All Superinterfaces:

Instance
```
public interface ISemaphore
extends Instance
```
ISemaphore is a backed-up distributed implementation of java.util.concurrent.Semaphore.
Hazelcast's ISemaphore is a cluster-wide counting semaphore. Conceptually, it maintains a set of permits. Each acquire() blocks if necessary until a permit is available, and then takes it. Each release() adds a permit, potentially releasing a blocking acquirer. However, no actual permit objects are used; the semaphore just keeps a count of the number available and acts accordingly.
The Hazelcast distributed semaphore implementation guarantees that threads invoking any of the acquire methods are selected to obtain permits in the order in which their invocation of those methods was processed(first-in-first-out; FIFO). Note that FIFO ordering necessarily applies to specific internal points of execution within the cluster. So, it is possible for one member to invoke acquire before another, but reach the ordering point after the other, and similarly upon return from the method.
The Hazelcast semaphore also allows you to attach()/detach() permits to the caller address. This provides a safety mechanism in case that address becomes disconnected from the cluster. Attached permits will automatically be released to the semaphore if a disconnection occurs. An address can also have an excess number of detached permits and is represented by a negative attached permit count. This is the number of permits that the semaphore will automatically be reduced by if a disconnection occurs.
This class also provides convenience methods to acquire and release multiple permits at a time. Beware of the increased risk of indefinite postponement when using the multiple acquire. If a single permit is released to a semaphore that is currently blocking, a thread waiting for one permit will acquire it before a thread waiting for multiple permits regardless of the call order.
- Correct usage of a semaphore is established by programming convention in the application.
Since:

1.9.3

Nested Class Summary
- Nested classes/interfaces inherited from interface com.hazelcast.core.Instance
  Instance.InstanceType

Method Summary

Methods
Modifier and Type	Method and Description
`void`	`acquire()` Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one.
`void`	`acquire(int permits)` Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount.
`Future`	`acquireAsync()` Asynchronously acquires a permit.
`Future`	`acquireAsync(int permits)` Asynchronously acquires a given number of permits.
`void`	`acquireAttach()` Acquires and attaches a permit to the caller's address.
`void`	`acquireAttach(int permits)` Acquires and attaches the given number of permits to the caller's address.
`Future`	`acquireAttachAsync()` Asynchronously acquires and attaches a permit to the caller's address.
`Future`	`acquireAttachAsync(int permits)` Asynchronously acquires and attaches the given number of permits to the caller's address.
`void`	`attach()` Attaches a permit to the caller's address.
`void`	`attach(int permits)` Attaches the given number of permits to the caller's address.
`int`	`attachedPermits()` Returns the current number of permits attached to the caller's address.
`int`	`availablePermits()` Returns the current number of permits currently available in this semaphore.
`void`	`detach()` Detaches a permit from the caller's address.
`void`	`detach(int permits)` Detaches the given number of permits from the caller's address.
`int`	`drainPermits()` Acquires and returns all permits that are immediately available.
`LocalSemaphoreStats`	`getLocalSemaphoreStats()`
`String`	`getName()` Returns the name of this ISemaphore instance.
`void`	`reducePermits(int reduction)` Shrinks the number of available permits by the indicated reduction.
`void`	`release()` Releases a permit, increasing the number of available permits by one.
`void`	`release(int permits)` Releases the given number of permits, increasing the number of available permits by that amount.
`void`	`releaseDetach()` Detaches a permit from the caller's address and returns it to the semaphore.
`void`	`releaseDetach(int permits)` Detaches the given number of permits from the caller's address and returns them to the semaphore.
`boolean`	`tryAcquire()` Acquires a permit, if one is available and returns immediately, with the value `true`, reducing the number of available permits by one.
`boolean`	`tryAcquire(int permits)` Acquires the given number of permits, if they are available, and returns immediately, with the value `true`, reducing the number of available permits by the given amount.
`boolean`	`tryAcquire(int permits, long timeout, TimeUnit unit)` Acquires the given number of permits, if they are available and returns immediately, with the value `true`, reducing the number of available permits by the given amount.
`boolean`	`tryAcquire(long timeout, TimeUnit unit)` Acquires a permit from this semaphore, if one becomes available within the given waiting time and the current thread has not been interrupted.
`boolean`	`tryAcquireAttach()` Acquires a permit from this semaphore and attaches it to the calling member, only if one is available at the time of invocation.
`boolean`	`tryAcquireAttach(int permits)` Acquires the given number of permits from this semaphore and attaches them to the calling member, only if all are available at the time of invocation.
`boolean`	`tryAcquireAttach(int permits, long timeout, TimeUnit unit)` Acquires the given number of permits from this semaphore and attaches them to the calling member, only if all become available within the given waiting time and the current thread has not been interrupted or the instance destroyed.
`boolean`	`tryAcquireAttach(long timeout, TimeUnit unit)` Acquires a permit from this semaphore and attaches it to the calling member, only if one becomes available within the given waiting time and the current thread has not been interrupted or the instance destroyed.

Methods inherited from interface com.hazelcast.core.Instance
destroy, getId, getInstanceType

- Method Detail
  - getName
```
String getName()
```
    Returns the name of this ISemaphore instance.
    
    Returns:
    name of this instance
  - acquire
```
void acquire()
             throws InstanceDestroyedException,
                    InterruptedException
```
    Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one.
    
    If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:
    - Some other thread invokes one of the release() methods for this semaphore and the current thread is next to be assigned a permit;
    - This ISemaphore instance is destroyed; or
    - Some other thread interrupts the current thread.
    If the ISemaphore instance is destroyed while the thread is waiting then InstanceDestroyedException will be thrown.
    If the current thread:
    - has its interrupted status set on entry to this method; or
    - is interrupted while waiting for a permit,
    then InterruptedException is thrown and the current thread's interrupted status is cleared.
    Throws:
    
    InstanceDestroyedException - if the instance is destroyed while waiting
    
    InterruptedException - if the current thread is interrupted
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
  - acquire
```
void acquire(int permits)
             throws InstanceDestroyedException,
                    InterruptedException
```
    Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount.
    
    If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:
    - Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request;
    - This ISemaphore instance is destroyed; or
    - Some other thread interrupts the current thread.
    If the ISemaphore instance is destroyed while waiting then InstanceDestroyedException will be thrown.
    If the current thread:
    - has its interrupted status set on entry to this method; or
    - is interrupted while waiting for a permit,
    then InterruptedException is thrown and the current thread's interrupted status is cleared.
    Parameters:
    permits - the number of permits to acquire
    
    Throws:
    
    InstanceDestroyedException - if the instance is destroyed while waiting
    
    InterruptedException - if the current thread is interrupted
    
    IllegalArgumentException - if permits is negative
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
  - acquireAsync
```
Future acquireAsync()
```
    Asynchronously acquires a permit.
```
 Future future = semaphore.acquireAsync();
 // do some other stuff, when ready get the result
 Object value = future.get();
 
```
    Future.get() will block until the actual acquire() completes. If the application requires timely response, then Future.get(timeout, timeunit) can be used.
```
 Future future = semaphore.acquireAsync();
 try{
   Object value = future.get(40, TimeUnit.MILLISECOND);
 }catch (TimeoutException t) {
   // time wasn't enough
 }
 
```
    This method itself does not throw any exceptions. Exceptions occur during the future.get() operation.
    
    If insufficient permits are available when calling future.get() then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of four things happens:
    - Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request;
    - This ISemaphore instance is destroyed;
    - The get method is called with a waiting time that elapses; or
    - Some other thread interrupts the current thread.
    If the ISemaphore instance is destroyed while the future.get() is waiting then ExecutionException will be thrown with InstanceDestroyedException set as it's cause.
    If the Hazelcast instance is shutdows while the future.get() is waiting then IllegalStateException will be thrown.
    If when calling future.get() a timeout is specified and the a permit cannot be acquired within the timeout period TimeoutException will be thrown.
    If when calling future.get() the current thread:
    - has its interrupted status set on entry to this method; or
    - is interrupted while waiting for a permit,
    then InterruptedException is thrown and the current thread's interrupted status is cleared.
    If the thread future.get() throws an InterruptedException, the acquire request is still outstanding and future.get() may be called again. To cancel the actual acquire, future.cancel() must be called. If the cancel method returns false then it was too late to cancel the request and the permit was acquired. The future.cancel() mayInterruptIfRunning argument is ignored.
    Returns:
    Future from which the acquire result can be obtained.
    See Also:
    Future
  - acquireAsync
```
Future acquireAsync(int permits)
```
    Asynchronously acquires a given number of permits.
    See acquireAsync().
    
    Parameters:
    permits - the number of permits to acquire
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - acquireAttach
```
void acquireAttach()
                   throws InstanceDestroyedException,
                          InterruptedException
```
    Acquires and attaches a permit to the caller's address.
    See acquire() and attach().
    
    Throws:
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
    
    InstanceDestroyedException
    
    InterruptedException
  - acquireAttach
```
void acquireAttach(int permits)
                   throws InstanceDestroyedException,
                          InterruptedException
```
    Acquires and attaches the given number of permits to the caller's address.
    See acquire() and attach().
    
    Parameters:
    permits - the number of permits to acquire and attach
    
    Throws:
    
    IllegalArgumentException - if permits is negative
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
    
    InstanceDestroyedException
    
    InterruptedException
  - acquireAttachAsync
```
Future acquireAttachAsync()
```
    Asynchronously acquires and attaches a permit to the caller's address.
    See acquireAsync() and attach().
  - acquireAttachAsync
```
Future acquireAttachAsync(int permits)
```
    Asynchronously acquires and attaches the given number of permits to the caller's address.
    See acquireAsync() and attach().
    
    Parameters:
    permits - the number of permits to acquire and attach
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - attach
```
void attach()
```
    Attaches a permit to the caller's address.
    See attachedPermits().
  - attach
```
void attach(int permits)
```
    Attaches the given number of permits to the caller's address.
    See attachedPermits().
    
    Parameters:
    permits - the number of permits to attach
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - attachedPermits
```
int attachedPermits()
```
    Returns the current number of permits attached to the caller's address. This value has no affect on the semaphores operation unless the caller address actually becomes disconnected.
    Positive value is the number of permits that will automatically be released to the semaphore if the caller address becomes disconnected from the cluster.
    Negative value represents the number of permits that the semaphore will automatically be reduced by if the caller address becomes disconnected from the cluster.
    - This method is typically used for debugging and testing purposes.
    Returns:
    the number of permits attached to caller addresses
  - availablePermits
```
int availablePermits()
```
    Returns the current number of permits currently available in this semaphore.
    - This method is typically used for debugging and testing purposes.
    Returns:
    the number of permits available in this semaphore
  - detach
```
void detach()
```
    Detaches a permit from the caller's address.
    See attachedPermits().
  - detach
```
void detach(int permits)
```
    Detaches the given number of permits from the caller's address.
    See attachedPermits().
    
    Parameters:
    permits - the number of permits to detach
  - drainPermits
```
int drainPermits()
```
    Acquires and returns all permits that are immediately available.
    
    Returns:
    the number of permits drained
  - reducePermits
```
void reducePermits(int reduction)
```
    Shrinks the number of available permits by the indicated reduction. This method differs from acquire in that it does not block waiting for permits to become available.
    
    Parameters:
    reduction - the number of permits to remove
    
    Throws:
    
    IllegalArgumentException - if reduction is negative
  - release
```
void release()
```
    Releases a permit, increasing the number of available permits by one. If any threads in the cluster are trying to acquire a permit, then one is selected and given the permit that was just released.
    There is no requirement that a thread that releases a permit must have acquired that permit by calling one of the acquire methods. Correct usage of a semaphore is established by programming convention in the application.
  - release
```
void release(int permits)
```
    Releases the given number of permits, increasing the number of available permits by that amount.
    There is no requirement that a thread that releases a permit must have acquired that permit by calling one of the acquire methods. Correct usage of a semaphore is established by programming convention in the application.
    
    Parameters:
    permits - the number of permits to release
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - releaseDetach
```
void releaseDetach()
```
    Detaches a permit from the caller's address and returns it to the semaphore.
    See release() and detach().
  - releaseDetach
```
void releaseDetach(int permits)
```
    Detaches the given number of permits from the caller's address and returns them to the semaphore.
    See release(int) and detach().
    
    Parameters:
    permits - the number of permits to release and detach
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - tryAcquire
```
boolean tryAcquire()
```
    Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one.
    If no permit is available then this method will return immediately with the value false.
    
    Returns:
    true if a permit was acquired and false otherwise
  - tryAcquire
```
boolean tryAcquire(int permits)
```
    Acquires the given number of permits, if they are available, and returns immediately, with the value true, reducing the number of available permits by the given amount.
    
    If insufficient permits are available then this method will return immediately with the value false and the number of available permits is unchanged.
    
    Parameters:
    permits - the number of permits to acquire
    
    Returns:
    true if the permits were acquired and false otherwise
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - tryAcquire
```
boolean tryAcquire(long timeout,
                 TimeUnit unit)
                   throws InstanceDestroyedException,
                          InterruptedException
```
    Acquires a permit from this semaphore, if one becomes available within the given waiting time and the current thread has not been interrupted.
    Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one.
    If no permit is available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:
    - Some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit; or
    - Some other thread interrupts the current thread; or
    - The specified waiting time elapses.
    If a permit is acquired then the value true is returned.
    If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.
    
    If the ISemaphore instance is destroyed while the thread is waiting then InstanceDestroyedException will be thrown.
    If the current thread:
    - has its interrupted status set on entry to this method; or
    - is interrupted while waiting for a permit,
    then InterruptedException is thrown and the current thread's interrupted status is cleared.
    Parameters:
    timeout - the maximum time to wait for a permit
    unit - the time unit of the timeout argument
    
    Returns:
    true if a permit was acquired and false if the waiting time elapsed before a permit was acquired
    
    Throws:
    
    InstanceDestroyedException - if the instance is destroyed while waiting
    
    InterruptedException - if the current thread is interrupted
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
  - tryAcquire
```
boolean tryAcquire(int permits,
                 long timeout,
                 TimeUnit unit)
                   throws InstanceDestroyedException,
                          InterruptedException
```
    Acquires the given number of permits, if they are available and returns immediately, with the value true, reducing the number of available permits by the given amount.
    If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of three things happens:
    - Some other thread invokes one of the release methods for this semaphore, the current thread is next to be assigned permits and the number of available permits satisfies this request; or
    - Some other thread interrupts the current thread; or
    - The specified waiting time elapses.
    If the permits are acquired then the value true is returned.
    If the specified waiting time elapses then the value false is returned. If the time is less than or equal to zero, the method will not wait at all.
    
    If the ISemaphore instance is destroyed while the thread is waiting then InstanceDestroyedException will be thrown.
    If the current thread:
    - has its interrupted status set on entry to this method; or
    - is interrupted while waiting for a permit,
    then InterruptedException is thrown and the current thread's interrupted status is cleared.
    Parameters:
    permits - the number of permits to acquire
    timeout - the maximum time to wait for the permits
    unit - the time unit of the timeout argument
    
    Returns:
    true if all permits were acquired and false if the waiting time elapsed before all permits could be acquired
    
    Throws:
    
    InstanceDestroyedException - if the instance is destroyed while waiting
    
    InterruptedException - if the current thread is interrupted
    
    IllegalArgumentException - if permits is negative
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
  - tryAcquireAttach
```
boolean tryAcquireAttach()
```
    Acquires a permit from this semaphore and attaches it to the calling member, only if one is available at the time of invocation.
    See tryAcquire() and attach().
    
    Returns:
    true if permit was acquired and attached to the caller's address
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - tryAcquireAttach
```
boolean tryAcquireAttach(int permits)
```
    Acquires the given number of permits from this semaphore and attaches them to the calling member, only if all are available at the time of invocation.
    See tryAcquire(int permits) and attach(int).
    
    Parameters:
    permits - the number of permits to try to acquire and attach
    
    Returns:
    true if permit(s) were acquired and attached to the caller's address
    
    Throws:
    
    IllegalArgumentException - if permits is negative
  - tryAcquireAttach
```
boolean tryAcquireAttach(long timeout,
                       TimeUnit unit)
                         throws InstanceDestroyedException,
                                InterruptedException
```
    Acquires a permit from this semaphore and attaches it to the calling member, only if one becomes available within the given waiting time and the current thread has not been interrupted or the instance destroyed.
    If the ISemaphore instance is destroyed while the thread is waiting then InstanceDestroyedException will be thrown.
    See tryAcquire(long timeout, TimeUnit unit) and attach().
    
    Parameters:
    timeout - the maximum time to wait for a permit
    unit - unit the time unit of the timeout argument
    
    Returns:
    true if a permit was acquired and false if the waiting time elapsed before a permit could be acquired
    
    Throws:
    
    InstanceDestroyedException - if the instance is destroyed while waiting
    
    InterruptedException - if the current thread is interrupted
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
  - tryAcquireAttach
```
boolean tryAcquireAttach(int permits,
                       long timeout,
                       TimeUnit unit)
                         throws InstanceDestroyedException,
                                InterruptedException
```
    Acquires the given number of permits from this semaphore and attaches them to the calling member, only if all become available within the given waiting time and the current thread has not been interrupted or the instance destroyed.
    See tryAcquire(int permits, long timeout, TimeUnit unit) and attach(int).
    
    Parameters:
    permits - the number of permits to try to acquire and attach
    timeout - the maximum time to wait for the permits
    unit - unit the time unit of the timeout argument
    
    Returns:
    true if permit(s) were acquired and attached to the caller's address and false if the waiting time elapsed before the permits could be acquired
    
    Throws:
    
    InstanceDestroyedException - if the instance is destroyed while waiting
    
    InterruptedException - if the current thread is interrupted
    
    IllegalArgumentException - if permits is negative
    
    IllegalStateException - if hazelcast instance is shutdown while waiting
  - getLocalSemaphoreStats
```
LocalSemaphoreStats getLocalSemaphoreStats()
```

Interface ISemaphore

Nested Class Summary

Nested classes/interfaces inherited from interface com.hazelcast.core.Instance

Method Summary

Methods inherited from interface com.hazelcast.core.Instance

Method Detail

getName

acquire

acquire

acquireAsync

acquireAsync

acquireAttach

acquireAttach

acquireAttachAsync

acquireAttachAsync

attach

attach

attachedPermits

availablePermits

detach

detach

drainPermits

reducePermits

release

release

releaseDetach

releaseDetach

tryAcquire

tryAcquire

tryAcquire

tryAcquire

tryAcquireAttach

tryAcquireAttach

tryAcquireAttach

tryAcquireAttach

getLocalSemaphoreStats