Module org.tquadrat.foundation.util

Package org.tquadrat.foundation.util.internal

Class TimeoutSemaphoreImpl

java.lang.Object

java.util.concurrent.Semaphore

org.tquadrat.foundation.util.internal.TimeoutSemaphoreImpl

All Implemented Interfaces:

Serializable, AutoSemaphore

@ClassVersion(sourceVersion="$Id: TimeoutSemaphoreImpl.java 1136 2024-05-30 18:25:38Z tquadrat $")
@API(status=STABLE,
     since="0.4.8")
public final class TimeoutSemaphoreImpl
extends Semaphore
implements AutoSemaphore

An implementation for AutoSemaphore that allows a timeout for the permits.

Author:

Thomas Thrien (thomas.thrien@tquadrat.org)

Version:

$Id: TimeoutSemaphoreImpl.java 1136 2024-05-30 18:25:38Z tquadrat $

Since:

0.4.8

See Also:

• Serialized Form

UML Diagram

⁠

UML Diagram for "org.tquadrat.foundation.util.internal.TimeoutSemaphoreImpl"

⁠

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private static final class	TimeoutSemaphoreImpl.Janitor	The Janitor for the owning TimeoutSemaphoreImpl instance.
private final class	TimeoutSemaphoreImpl.Reaper	The reaper thread.
private final class	TimeoutSemaphoreImpl.Token	The token that holds the permits to be released when a try-with-resources block is left or the timeout has expired.

Field Summary

Fields

Modifier and Type	Field	Description
private final Cleaner.Cleanable	m_Cleanable	The Cleaner.Cleanable for this instance.
private static final Cleaner	m_Cleaner	The cleaner that is used for the instances of this class.
private final TimeoutSemaphoreImpl.Janitor	m_Janitor	The janitor for instances of this class.
private final AutoLock	m_Lock	The lock that guards the access to m_Registry.
private final ScheduledExecutorService	m_ReaperExecutor	The executor for the reaper.
private final Map<UUID,TimeoutSemaphoreImpl.Token>	m_Registry	The permit registry.
private final Duration	m_Timeout	The timeout duration.
static final long	REAPER_CYCLE	The cycle time for the reaper thread in milliseconds: 1000L ms.

Constructor Summary

Constructors

Constructor	Description
TimeoutSemaphoreImpl(int permits, boolean fair, Duration timeout)	Creates an TimeoutSemaphoreImpl instance with the given number of permits, the given timeout duration and the given fairness setting.
TimeoutSemaphoreImpl(int permits, Duration timeout)	Creates an TimeoutSemaphoreImpl instance with the given number of permits, the given timeout duration and non-fair fairness setting.

Method Summary

Modifier and Type	Method	Description
AutoCloseable	acquireToken(int permits)	Acquires the given number of permits from this semaphore, blocking until all are available, or the thread is interrupted, and returns a token object that is used for try-with-resources.
AutoCloseable	acquireTokenUninterruptibly(int permits)	Acquires the given number of permits from this semaphore, blocking until all are available, and returns a token object that is used for try-with-resources.
private final TimeoutSemaphoreImpl.Token	createToken(int permits)	Creates a token and adds to the registry.
final Semaphore	getSemaphore()	Returns a reference to the raw semaphore.
private final Cleaner.Cleanable	registerJanitor(Runnable janitor)	Registers the janitor that is doing the housekeeping on garbage collection.
final void	release(UUID id)	Releases the number of permits associated with the token with the given id, returning them to the semaphore.

Methods inherited from class java.util.concurrent.Semaphore

acquire, acquire, acquireUninterruptibly, acquireUninterruptibly, availablePermits, drainPermits, getQueuedThreads, getQueueLength, hasQueuedThreads, isFair, reducePermits, release, release, toString, tryAcquire, tryAcquire, tryAcquire, tryAcquire

Methods inherited from class java.lang.Object

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

Methods inherited from interface org.tquadrat.foundation.util.AutoSemaphore

acquireToken, acquireTokenUninterruptibly

Field Details

REAPER_CYCLE

public static final long REAPER_CYCLE

The cycle time for the reaper thread in milliseconds: 1000L ms.

See Also:

• Constant Field Values

m_Cleanable

private final transient Cleaner.Cleanable m_Cleanable

The Cleaner.Cleanable for this instance. As instances of this class does not support close() or something similar, keeping the reference to the Cleanable is considered obsolete. But we keep it anyway, in case this changes.

m_Janitor

private final transient TimeoutSemaphoreImpl.Janitor m_Janitor

The janitor for instances of this class.

m_Lock

private final transient AutoLock m_Lock

The lock that guards the access to m_Registry.

m_Timeout

private final Duration m_Timeout

The timeout duration.

m_ReaperExecutor

private final transient ScheduledExecutorService m_ReaperExecutor

The executor for the reaper.

m_Registry

private final transient Map<UUID,TimeoutSemaphoreImpl.Token> m_Registry

The permit registry.

m_Cleaner

private static final Cleaner m_Cleaner

The cleaner that is used for the instances of this class.

Constructor Details

TimeoutSemaphoreImpl

public TimeoutSemaphoreImpl(int permits,
 Duration timeout)

Creates an TimeoutSemaphoreImpl instance with the given number of permits, the given timeout duration and non-fair 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.

timeout - The timeout.

TimeoutSemaphoreImpl

public TimeoutSemaphoreImpl(int permits,
 boolean fair,
 Duration timeout)

Creates an TimeoutSemaphoreImpl instance with the given number of permits, the given timeout duration 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.

timeout - The timeout.

Method Details

acquireToken

public AutoCloseable acquireToken(int permits)
                           throws InterruptedException,
IllegalArgumentException

Acquires the given number of permits from this semaphore, blocking until all are available, or the thread is interrupted, and returns a token object that is used for try-with-resources.

Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount. This method atomically acquires the permits all at once.

If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until one of two things happens:

• Some other thread invokes one of the release() methods for this semaphore and 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.

If the current thread:

• has its interrupted status set on entry to this method; or
• is interrupted while waiting for a permit,

then an InterruptedException is thrown and the current thread's interrupted status is cleared. Any permits that were to be assigned to this thread are instead assigned to other threads trying to acquire permits, as if permits had been made available by a call to release().

Specified by:

acquireToken in interface AutoSemaphore

Parameters:

permits - The number of permits to acquire.

Returns:

The token.

Throws:

InterruptedException - The current thread is interrupted.

IllegalArgumentException - The given number of permits to acquire is negative.

acquireTokenUninterruptibly

public AutoCloseable acquireTokenUninterruptibly(int permits)
                                          throws IllegalArgumentException

Acquires the given number of permits from this semaphore, blocking until all are available, and returns a token object that is used for try-with-resources.

Acquires the given number of permits, if they are available, and returns immediately, reducing the number of available permits by the given amount. This method atomically acquires the permits all at once.

If insufficient permits are available then the current thread becomes disabled for thread scheduling purposes and lies dormant until some other thread invokes one of the release() methods for this semaphore and the current thread is next to be assigned permits and the number of available permits satisfies this request.

If the current thread is interrupted while waiting for permits then it will continue to wait and its position in the queue is not affected. When the thread does return from this method its interrupt status will be set.

Specified by:

acquireTokenUninterruptibly in interface AutoSemaphore

Parameters:

permits - The number of permits to acquire.

Returns:

The token.

Throws:

IllegalArgumentException - The given number of permits to acquire is negative.

createToken

private final TimeoutSemaphoreImpl.Token createToken(int permits)

Creates a token and adds to the registry.

Parameters:

permits - The number of permits to acquire.

Returns:

The new token.

getSemaphore

public final Semaphore getSemaphore()

Returns a reference to the raw semaphore.

Specified by:

getSemaphore in interface AutoSemaphore

Returns:

The semaphore.

registerJanitor

private final Cleaner.Cleanable registerJanitor(Runnable janitor)

Registers the janitor that is doing the housekeeping on garbage collection.

Parameters:

janitor - The janitor.

Returns:

The Cleaner.Cleanable for this instance.

release

public final void release(UUID id)

Releases the number of permits associated with the token with the given id, returning them to the semaphore.

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

Nothing happens if the token with given id had died already.

Parameters:

id - The id of the token.