public interface ISemaphore extends DistributedObject
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. Therefore,
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.
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.
|
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 the 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.
|
destroy, getPartitionKey, getServiceName
String getName()
getName
in interface DistributedObject
boolean init(int permits)
permits
- the given permit countvoid 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:
release()
methods for this
semaphore and the current thread is next to be assigned a permit,
If the current thread:
InterruptedException
is thrown and the current thread's
interrupted status is cleared.InterruptedException
- if the current thread is interruptedIllegalStateException
- if hazelcast instance is shutdown while waitingvoid 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:
release
methods for this semaphore, the current thread is next to be assigned
permits and the number of available permits satisfies this request,
If the current thread:
InterruptedException
is thrown and the current thread's
interrupted status is cleared.permits
- the number of permits to acquireInterruptedException
- if the current thread is interruptedIllegalArgumentException
- if permits
is negativeIllegalStateException
- if hazelcast instance is shutdown while waitingint availablePermits()
int drainPermits()
void reducePermits(int reduction)
acquire
in that it does not
block waiting for permits to become available.reduction
- the number of permits to removeIllegalArgumentException
- if reduction
is negativevoid release()
acquire
methods.
Correct usage of a semaphore is established by programming convention
in the application.void release(int permits)
acquire
methods.
Correct usage of a semaphore is established by programming convention
in the application.permits
- the number of permits to releaseIllegalArgumentException
- if permits
is negativeboolean tryAcquire()
true
,
reducing the number of available permits by one.
If no permit is available then this method will return
immediately with the value false
.true
if a permit was acquired and false
otherwiseboolean tryAcquire(int permits)
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.
permits
- the number of permits to acquiretrue
if the permits were acquired and
false
otherwiseIllegalArgumentException
- if permits
is negativeboolean tryAcquire(long timeout, TimeUnit unit) throws InterruptedException
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:
release()
method for this
semaphore and the current thread is next to be assigned a permit, or
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:
InterruptedException
is thrown and the current thread's
interrupted status is cleared.timeout
- the maximum time to wait for a permitunit
- the time unit of the timeout
argumenttrue
if a permit was acquired and false
if the waiting time elapsed before a permit was acquiredInterruptedException
- if the current thread is interruptedIllegalStateException
- if hazelcast instance is shutdown while waitingboolean tryAcquire(int permits, long timeout, TimeUnit unit) throws InterruptedException
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:
release
methods for this semaphore, the current thread is next to be assigned
permits and the number of available permits satisfies this request, or
true
is returned.
If the specified waiting time elapses then false
is returned. If the time is less than or equal to zero, the method
will not wait at all.
If the current thread:
InterruptedException
is thrown and the current thread's
interrupted status is cleared.permits
- the number of permits to acquiretimeout
- the maximum time to wait for the permitsunit
- the time unit of the timeout
argumenttrue
if all permits were acquired, false
if the waiting time elapsed before all permits could be acquiredInterruptedException
- if the current thread is interruptedIllegalArgumentException
- if permits
is negativeIllegalStateException
- if hazelcast instance is shutdown while waitingCopyright © 2016 Hazelcast, Inc.. All Rights Reserved.