com.hazelcast.core
Interface ISemaphore

All Superinterfaces:
DistributedObject

public interface ISemaphore
extends DistributedObject

ISemaphore is a backed-up distributed alternative to the Semaphore.

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.

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.


Method Summary
 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.
 int availablePermits()
          Returns the current number of permits currently available in this semaphore.
 int drainPermits()
          Acquires and returns all permits that are immediately available.
 String getName()
          Returns the name of this ISemaphore instance.
 boolean init(int permits)
          Try to initialize this ISemaphore instance with given permit count
 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.
 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.
 
Methods inherited from interface com.hazelcast.core.DistributedObject
destroy, getId, getPartitionKey, getServiceName
 

Method Detail

getName

String getName()
Returns the name of this ISemaphore instance.

Specified by:
getName in interface DistributedObject
Returns:
name of this instance

init

boolean init(int permits)
Try to initialize this ISemaphore instance with given permit count

Returns:
true if initialization success

acquire

void acquire()
             throws 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:

If the current thread:

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Throws:
InterruptedException - if the current thread is interrupted
IllegalStateException - if hazelcast instance is shutdown while waiting

acquire

void acquire(int permits)
             throws 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:

If the current thread:

then InterruptedException is thrown and the current thread's interrupted status is cleared.

Parameters:
permits - the number of permits to acquire
Throws:
InterruptedException - if the current thread is interrupted
IllegalArgumentException - if permits is negative
IllegalStateException - if hazelcast instance is shutdown while waiting

availablePermits

int availablePermits()
Returns the current number of permits currently available in this semaphore.

Returns:
the number of permits available in this semaphore

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

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 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:

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 current thread:

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:
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 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:

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 current thread:

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:
InterruptedException - if the current thread is interrupted
IllegalArgumentException - if permits is negative
IllegalStateException - if hazelcast instance is shutdown while waiting


Copyright © 2014 Hazelcast, Inc.. All Rights Reserved.