Module org.tquadrat.foundation.util
Package org.tquadrat.foundation.util

Interface AutoSemaphore

All Known Implementing Classes:
AutoSemaphoreImpl, TimeoutSemaphoreImpl
@ClassVersion(sourceVersion="$Id: AutoSemaphore.java 1136 2024-05-30 18:25:38Z tquadrat $") @API(status=STABLE, since="0.4.8") public sealed interface AutoSemaphore permits AutoSemaphoreImpl, TimeoutSemaphoreImpl

An implementation of Semaphore that allows to be used with try-with-resources.

Use this class like this:


  final static final int MAX_AVAILABLE = …
  final AutoSemaphore semaphore = AutoSemaphore.of( MAX_AVAILABLE );
  …
  try( final var token = semaphore.acquireToken() )
  {
      // Do something …
  }
  catch( final InterruptedException e )
  {
      // Handle the exception …
  }

A call to of(int,Duration) or of(int,boolean,Duration) creates a AutoSemaphore instance whose permits will be released automatically after the given period of time. Do not acquire permits from the instance returned by a call to getSemaphore() on such an instance, as it may behave unexpectedly.

Author:
Thomas Thrien (thomas.thrien@tquadrat.org)
Version:
$Id: AutoSemaphore.java 1136 2024-05-30 18:25:38Z tquadrat $
Since:
0.4.8
UML Diagram
UML Diagram for "org.tquadrat.foundation.util.AutoSemaphore"⁠

UML Diagram for "org.tquadrat.foundation.util.AutoSemaphore"

UML Diagram for "org.tquadrat.foundation.util.AutoSemaphore"⁠

  • Method Summary

    Modifier and Type
    Method
    Description
    default AutoCloseable
    acquireToken()
    Acquires a permit from this semaphore, blocking until one is available, or the thread is interrupted, and returns a token object that is used for try-with-resources.
    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.
    default AutoCloseable
    acquireTokenUninterruptibly()
    Acquires a permit from this semaphore, blocking until one is available, 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.
    Semaphore
    getSemaphore()
    Returns a reference to the raw semaphore.
    static AutoSemaphore
    of(int permits)
    Creates an AutoSemaphore instance with the given number of permits and non-fair fairness setting.
    static AutoSemaphore
    of(int permits, boolean fair)
    Creates an AutoSemaphore instance with the given number of permits and the given fairness setting.
    static AutoSemaphore
    of(int permits, boolean fair, Duration duration)
    Creates an AutoSemaphore instance with the given number of permits and the given fairness setting.
    static AutoSemaphore
    of(int permits, Duration duration)
    Creates an AutoSemaphore instance with the given number of permits and non-fair fairness setting.

  • Method Details

    • acquireToken

      default AutoCloseable acquireToken() throws InterruptedException

      Acquires a permit from this semaphore, blocking until one is available, or the thread is interrupted, and returns a token object that is used for try-with-resources.

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

      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.
      Returns:
      The token.
      Throws:
      InterruptedException - The current thread was interrupted.

    • acquireToken

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

      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

      default AutoCloseable acquireTokenUninterruptibly()

      Acquires a permit from this semaphore, blocking until one is available, and returns a token object that is used for try-with-resources.

      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 some other thread invokes the release() method for this semaphore and the current thread is next to be assigned a permit.

      If the current thread is interrupted while waiting for a permit then it will continue to wait, but the time at which the thread is assigned a permit may change compared to the time it would have received the permit had no interruption occurred. When the thread does return from this method its interrupt status will be set.

      Returns:
      The token.

    • acquireTokenUninterruptibly

      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.

      Parameters:
      permits - The number of permits to acquire.
      Returns:
      The token.
      Throws:
      IllegalArgumentException - The given number of permits to acquire is negative.

    • getSemaphore

      Semaphore getSemaphore()
      Returns a reference to the raw semaphore.
      Returns:
      The semaphore.

    • of

      static AutoSemaphore of(int permits)
      Creates an AutoSemaphore instance with the given number of permits 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.
      Returns:
      The new AutoSemaphore instance.

    • of

      static AutoSemaphore of(int permits, boolean fair)
      Creates an AutoSemaphore instance 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.
      Returns:
      The new AutoSemaphore instance.

    • of

      static AutoSemaphore of(int permits, Duration duration)
      Creates an AutoSemaphore instance with the given number of permits 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.
      duration - The timeout for a permit; after the given period of time, an acquired permit will be released automatically.
      Returns:
      The new AutoSemaphore instance.

    • of

      static AutoSemaphore of(int permits, boolean fair, Duration duration)
      Creates an AutoSemaphore instance 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.
      duration - The timeout for a permit; after the given period of time, an acquired permit will be released automatically.
      Returns:
      The new AutoSemaphore instance.