ISemaphore is a backed-up distributed alternative to the java.util.concurrent.Semaphore. More...

#include <ISemaphore.h>

Inheritance diagram for hazelcast::client::ISemaphore:

Public Member Functions
bool	init (int permits)
	Try to initialize this ISemaphore instance with given permit count. More...

void	acquire ()
	Acquires a permit, if one is available and returns immediately, reducing the number of available permits by one. More...

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. More...

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

int	drainPermits ()
	Acquires and returns all permits that are immediately available. More...

void	reducePermits (int reduction)
	Shrinks the number of available permits by the indicated reduction. More...

void	increasePermits (int32_t increase)
	Increases the number of available permits by the indicated amount. More...

void	release ()
	Releases a permit, increasing the number of available permits by one. More...

void	release (int permits)
	Releases the given number of permits, increasing the number of available permits by that amount. More...

bool	tryAcquire ()
	Acquires a permit, if one is available and returns immediately, with the value true, reducing the number of available permits by one. More...

bool	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. More...

bool	tryAcquire (long timeoutInMillis)
	Acquires a permit from this semaphore, if one becomes available within the given waiting time and the current thread has not been interrupted. More...

bool	tryAcquire (int permits, long timeoutInMillis)
	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. More...

Friends
class	impl::HazelcastClientInstanceImpl

Detailed Description

ISemaphore is a backed-up distributed alternative to the java.util.concurrent.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 according ly. 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(int) 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.

Member Function Documentation

◆ acquire() [1/2]

void hazelcast::client::ISemaphore::acquire ( )

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

Exceptions

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

◆ acquire() [2/2]

void hazelcast::client::ISemaphore::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.

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() 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 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

Exceptions

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

◆ availablePermits()

int hazelcast::client::ISemaphore::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

◆ drainPermits()

int hazelcast::client::ISemaphore::drainPermits ( )

Acquires and returns all permits that are immediately available.

Returns: the number of permits drained

◆ increasePermits()

void hazelcast::client::ISemaphore::increasePermits ( int32_t increase )

Increases the number of available permits by the indicated amount.

This method differs from

release

in that it does not effect the amount of permits this caller has attached.

Parameters

increase the number of permits to add

Exceptions

IllegalArgumentException

if

increase

is negative

◆ init()

bool hazelcast::client::ISemaphore::init ( int permits )

Try to initialize this ISemaphore instance with given permit count.

Returns: true if initialization success

◆ reducePermits()

void hazelcast::client::ISemaphore::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

Exceptions

IllegalArgumentException if reduction is negative

◆ release() [1/2]

void hazelcast::client::ISemaphore::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() acquire methods. Correct usage of a semaphore is established by programming convention in the application.

◆ release() [2/2]

void hazelcast::client::ISemaphore::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() acquire methods. Correct usage of a semaphore is established by programming convention in the application.

Parameters

permits the number of permits to release

◆ tryAcquire() [1/4]

bool hazelcast::client::ISemaphore::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() [2/4]

bool hazelcast::client::ISemaphore::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

◆ tryAcquire() [3/4]

bool hazelcast::client::ISemaphore::tryAcquire ( long timeoutInMillis )

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

timeoutInMillis the maximum time to wait for a permit

Returns: true if a permit was acquired and false if the waiting time elapsed before a permit was acquired

Exceptions

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

◆ tryAcquire() [4/4]

bool hazelcast::client::ISemaphore::tryAcquire	(	int	permits,
		long	timeoutInMillis
	)

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() 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 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
timeoutInMillis	the maximum time to wait for the permits

Returns: true if all permits were acquired and false if the waiting time elapsed before all permits could be acquired

Exceptions

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

The documentation for this class was generated from the following files:

hazelcast/include/hazelcast/client/ISemaphore.h
hazelcast/src/hazelcast/client/ISemaphore.cpp

Public Member Functions

Friends

Detailed Description

Member Function Documentation

◆ acquire() [1/2]

◆ acquire() [2/2]

◆ availablePermits()

◆ drainPermits()

◆ increasePermits()

◆ init()

◆ reducePermits()

◆ release() [1/2]

◆ release() [2/2]

◆ tryAcquire() [1/4]

◆ tryAcquire() [2/4]

◆ tryAcquire() [3/4]

◆ tryAcquire() [4/4]