io.vertxconcurrent

Class Semaphore

java.lang.Object

io.vertxconcurrent.Semaphore

public class Semaphore
extends Object

A counting semaphore. Conceptually, a semaphore maintains a set of permits. Each acquire(int, java.lang.Runnable) waits if necessary until a permit is available, and then executes the provided callback. Each release(int) adds a permit, potentially releasing a waiting acquirer. By "wait", it is not meant that anything is blocking. In fact, acquire(int, java.lang.Runnable) will always return immediately, after either asynchronously executing the callback or enqueing it for later.

Semaphores are thread-safe and can be shared between different event loops and worker threads. When a callback is executed, it always runs on the same context as its acquire(int, java.lang.Runnable) call, even if it is triggered from a release(int) call from a different thread.

By default, permits will be released in an optimal order, meaning that a request for 10 permits will be given precedence over a request for 20 permits. The constructor for this class optionally accepts a fairness parameter. When this set is set to true, permits will be released according to the order in which they are acquired.

Author:

Rob Worsnop

Constructor Summary

Constructors

Constructor and Description
Semaphore(int permits, boolean fair, io.vertx.core.Vertx vertx) Creates a Semaphore with the given number of permits and the given fairness setting.
Semaphore(int permits, boolean fair, io.vertx.rxjava.core.Vertx vertx) Creates a Semaphore with the given number of permits and the given fairness setting.
Semaphore(int permits, io.vertx.core.Vertx vertx) Creates a Semaphore with the given number of permits and nonfair fairness setting.
Semaphore(int permits, io.vertx.rxjava.core.Vertx vertx) Creates a Semaphore with the given number of permits and nonfair fairness setting.

Method Summary

Modifier and Type	Method and Description
void	acquire(int permits, Runnable action) Acquires the given number of permits from this semaphore.
void	acquire(Runnable action) Acquires one permit from this semaphore.
int	drainPermits() Acquires and returns all permits that are immediately available.
int	getAvailablePermits() Returns the current number of permits available in this semaphore.
int	getQueueLength() Returns the number of enqueued requests waiting to acquire.
void	release() Releases one permit, returning it to the semaphore.
void	release(int permits) Releases the given number of permits, returning them to the semaphore.
boolean	tryAcquire() Acquires a permit from this semaphore, only if one is available at the time of invocation.
boolean	tryAcquire(int permits) Acquires the given number of permits from this semaphore, only if they are available at the time of invocation.
void	tryAcquire(int permits, long timeout, TimeUnit unit, Consumer<Boolean> resultHandler) Acquires the given number of permits from this semaphore, if all become available within the given waiting time.
void	tryAcqure(long timeout, TimeUnit unit, Consumer<Boolean> resultHandler) Acquires one permit from this semaphore, if it becomes available within the given waiting time.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Semaphore

public Semaphore(int permits,
                 io.vertx.core.Vertx vertx)

Creates a Semaphore with the given number of permits and nonfair fairness setting.

Parameters:

permits - the initial number of permits available. This value may be negative, in which case releases must occur before any acquires will be granted.

vertx - the Vertx instance.

Semaphore

public Semaphore(int permits,
                 boolean fair,
                 io.vertx.core.Vertx vertx)

Creates a Semaphore with the given number of permits and the given fairness setting.

Parameters:

permits - the initial number of permits available. This value may be negative, in which case releases must occur before any acquires will be granted.

fair - true if this semaphore will guarantee first-in first-out granting of permits under contention, else false

vertx - the Vertx instance.

Semaphore

public Semaphore(int permits,
                 io.vertx.rxjava.core.Vertx vertx)

Creates a Semaphore with the given number of permits and nonfair fairness setting.

Parameters:

permits - the initial number of permits available. This value may be negative, in which case releases must occur before any acquires will be granted.

vertx - the Vertx instance.

Semaphore

public Semaphore(int permits,
                 boolean fair,
                 io.vertx.rxjava.core.Vertx vertx)

Creates a Semaphore with the given number of permits and the given fairness setting.

Parameters:

permits - the initial number of permits available. This value may be negative, in which case releases must occur before any acquires will be granted.

fair - true if this semaphore will guarantee first-in first-out granting of permits under contention, else false

vertx - the Vertx instance.

Method Detail

acquire

public void acquire(int permits,
                    Runnable action)

Acquires the given number of permits from this semaphore.

Acquires the given number of permits, if they are available, and calls the action, reducing the number of available permits by the given amount.

If insufficient permits are available then the request to acquire them is enqueued until a call to release makes them available.

Parameters:

permits - the number of permits to acquire

action - the action to be called when permits are available.

Throws:

IllegalArgumentException - if permits is negative

acquire

public void acquire(Runnable action)

Acquires one permit from this semaphore.

Acquires one permit, if it is available, and calls the action, reducing the number of available permits by one.

If insufficient permits are available then the request to acquire it is enqueued until a call to release makes it available.

Parameters:

action - the action to be called when permits are available.

tryAcquire

public boolean tryAcquire(int permits)

Acquires the given number of permits from this semaphore, only if they are available at the time of invocation.

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.

Even when this semaphore has been set to use a fair ordering policy, a call to tryAcquire(int) will immediately acquire a permit if one is available, whether or not other attempts to acquire are currently waiting. This "barging" behavior can be useful in certain circumstances, even though it breaks fairness. If you want to honor the fairness setting, then use tryAcquire(int, long, TimeUnit, Consumer) which is almost equivalent.

Parameters:

permits - the number of permits to acquire

Returns:

true if a permit was acquired and false otherwise

tryAcquire

public boolean tryAcquire()

Acquires a permit from this semaphore, only if one is available at the time of invocation.

Acquires one permit, if it is available and returns immediately, with the value true, reducing the number of available permits by one.

If no permits are available then this method will return immediately with the value false.

Even when this semaphore has been set to use a fair ordering policy, a call to tryAcquire() will immediately acquire a permit if one is available, whether or not other attempts to acquire are currently waiting. This "barging" behavior can be useful in certain circumstances, even though it breaks fairness. If you want to honor the fairness setting, then use tryAcqure(long, TimeUnit, Consumer) which is almost equivalent.

Returns:

true if a permit was acquired and false otherwise

tryAcquire

public void tryAcquire(int permits,
                       long timeout,
                       TimeUnit unit,
                       Consumer<Boolean> resultHandler)

Acquires the given number of permits from this semaphore, if all become available within the given waiting time.

Acquires the given number of permits, if they are available, and immediately passes true to resultHandler, reducing the number of available permits by the given amount.

If insufficient permits are available then the request to acquire is enqueued until one of two things happens:

• The application invokes one of the release methods for this semaphore, this request is next to be assigned permits and the number of available permits satisfies this request; or
• The specified waiting time elapses.

If the permits are acquired then the value true is passed to resultHandler.

If the specified waiting time elapses then the value false is passed to resultHandler.

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

resultHandler - is passed true is the permits were acquired, otherwise false

Throws:

IllegalArgumentException - if permits is negative

tryAcqure

public void tryAcqure(long timeout,
                      TimeUnit unit,
                      Consumer<Boolean> resultHandler)

Acquires one permit from this semaphore, if it becomes available within the given waiting time.

Acquires one permit, if it is available, and immediately passes true to resultHandler, reducing the number of available permits by one.

If insufficient permits are available then the request to acquire is enqueued until one of two things happens:

• The application invokes one of the release methods for this semaphore, this request is next to be assigned permits and the number of available permits satisfies this request; or
• The specified waiting time elapses.

If the permit is acquired then the value true is passed to resultHandler.

If the specified waiting time elapses then the value false is passed to resultHandler.

Parameters:

timeout - the maximum time to wait for the permits

unit - the time unit of the timeout argument

resultHandler - is passed true is the permits were acquired, otherwise false

Throws:

IllegalArgumentException - if permits is negative

release

public void release(int permits)

Releases the given number of permits, returning them to the semaphore.

Releases the given number of permits, increasing the number of available permits by that amount.

If any enqueued requests are trying to acquire permits, then one is selected and given the permits that were just released. If the number of available permits satisfies that request then its action is invoked. If there are still permits available after this request has been satisfied, then those permits are assigned in turn to other requests trying to acquire permits.

Parameters:

permits - the number of permits to release

Throws:

IllegalArgumentException - if permits is negative

release

public void release()

Releases one permit, returning it to the semaphore.

Releases one permit, increasing the number of available permits by one.

If any enqueued requests are trying to acquire permits, then one is selected and given the permit that was just released. If the number of available permits satisfies that request then its action is invoked.

drainPermits

public int drainPermits()

Acquires and returns all permits that are immediately available.

Returns:

the number of permits acquired

getQueueLength

public int getQueueLength()

Returns the number of enqueued requests waiting to acquire.

Returns:

the number of enqueued requests waiting to acquire

getAvailablePermits

public int getAvailablePermits()

Returns the current number of permits available in this semaphore.

This method is typically used for debugging and testing purposes.

Returns:

the number of permits available in this semaphore