TimedSemaphore (Apache Commons Lang 3.20.0 API)
Description: declaration: package: org.apache.commons.lang3.concurrent, class: TimedSemaphore

# Class TimedSemaphore

java.lang.Object
org.apache.commons.lang3.concurrent.TimedSemaphore

public class TimedSemaphore extends Object
A specialized semaphore implementation that provides a number of permits in a given time frame.

This class is similar to the `Semaphore` class provided by the JDK in that it manages a configurable number of permits. Using the `acquire()` method a permit can be requested by a thread. However, there is an additional timing dimension: there is no `release()` method for freeing a permit, but all permits are automatically released at the end of a configurable time frame. If a thread calls `acquire()` and the available permits are already exhausted for this time frame, the thread is blocked. When the time frame ends all permits requested so far are restored, and blocking threads are waked up again, so that they can try to acquire a new permit. This basically means that in the specified time frame only the given number of operations is possible.

A use case for this class is to artificially limit the load produced by a process. As an example consider an application that issues database queries on a production system in a background process to gather statistical information. This background processing should not produce so much database load that the functionality and the performance of the production system are impacted. Here a `TimedSemaphore` could be installed to guarantee that only a given number of database queries are issued per second.

A thread class for performing database queries could look as follows:

    public class StatisticsThread extends Thread {
        // The semaphore for limiting database load.
        private final TimedSemaphore semaphore;
        // Create an instance and set the semaphore
        public StatisticsThread(TimedSemaphore timedSemaphore) {
            semaphore = timedSemaphore;
        }
        // Gather statistics
        public void run() {
            try {
                while (true) {
                    semaphore.acquire();   // limit database load
                    performQuery();        // issue a query
                }
            } catch (InterruptedException) {
                // fall through
            }
        }
        ...
    }

The following code fragment shows how a `TimedSemaphore` is created that allows only 10 operations per second and passed to the statistics thread:

    TimedSemaphore sem = new TimedSemaphore(1, TimeUnit.SECOND, 10);
    StatisticsThread thread = new StatisticsThread(sem);
    thread.start();

When creating an instance the time period for the semaphore must be specified. `TimedSemaphore` uses an executor service with a corresponding period to monitor this interval. The `ScheduledExecutorService` to be used for this purpose can be provided at construction time. Alternatively the class creates an internal executor service.

Client code that uses `TimedSemaphore` has to call the `acquire()` method in each processing step. `TimedSemaphore` keeps track of the number of invocations of the `acquire()` method and blocks the calling thread if the counter exceeds the limit specified. When the timer signals the end of the time period the counter is reset and all waiting threads are released. Then another cycle can start.

An alternative to `acquire()` is the `tryAcquire()` method. This method checks whether the semaphore is under the specified limit and increases the internal counter if this is the case. The return value is then true, and the calling thread can continue with its action. If the semaphore is already at its limit, `tryAcquire()` immediately returns false without blocking; the calling thread must then abort its action. This usage scenario prevents blocking of threads.

It is possible to modify the limit at any time using the `setLimit(int)` method. This is useful if the load produced by an operation has to be adapted dynamically. In the example scenario with the thread collecting statistics it may make sense to specify a low limit during day time while allowing a higher load in the night time. Reducing the limit takes effect immediately by blocking incoming callers. If the limit is increased, waiting threads are not released immediately, but wake up when the timer runs out. Then, in the next period more processing steps can be performed without blocking. By setting the limit to 0 the semaphore can be switched off: in this mode the `acquire()` method never blocks, but lets all callers pass directly.

When the `TimedSemaphore` is no more needed its `shutdown()` method should be called. This causes the periodic task that monitors the time interval to be canceled. If the `ScheduledExecutorService` has been created by the semaphore at construction time, it is also shut down. resources. After that `acquire()` must not be called any more.

Since:
  3.0

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `TimedSemaphore.Builder`
  Builds new `TimedSemaphore`.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `NO_LIMIT`
  Constant for a value representing no limit.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `TimedSemaphore(long timePeriod, TimeUnit timeUnit, int limit)`
  Deprecated.
  Use `builder()` and `TimedSemaphore.Builder`.
  `TimedSemaphore(ScheduledExecutorService service, long timePeriod, TimeUnit timeUnit, int limit)`
  Deprecated.
  Use `builder()` and `TimedSemaphore.Builder`.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `acquire()`
  Acquires a permit from this semaphore.
  `static TimedSemaphore.Builder`
  `builder()`
  Constructs a new Builder.
  `int`
  `getAcquireCount()`
  Gets the number of invocations of the `acquire()` method for the current period.
  `int`
  `getAvailablePermits()`
  Gets the number of calls to the `acquire()` method that can still be performed in the current period without blocking.
  `double`
  `getAverageCallsPerPeriod()`
  Gets the average number of successful (i.e. non-blocking) `acquire()` invocations for the entire life-time of this `TimedSemaphore`.
  `protected ScheduledExecutorService`
  `getExecutorService()`
  Gets the executor service used by this instance.
  `int`
  `getLastAcquiresPerPeriod()`
  Gets the number of (successful) acquire invocations during the last period.
  `final int`
  `getLimit()`
  Gets the limit enforced by this semaphore.
  `long`
  `getPeriod()`
  Gets the time period.
  `TimeUnit`
  `getUnit()`
  Gets the time unit.
  `boolean`
  `isShutdown()`
  Tests whether the `shutdown()` method has been called on this object.
  `final void`
  `setLimit(int limit)`
  Sets the limit.
  `void`
  `shutdown()`
  Initializes a shutdown.
  `protected ScheduledFuture<?>`
  `startTimer()`
  Starts the timer.
  `boolean`
  `tryAcquire()`
  Tries to acquire a permit from this semaphore.

  ### Methods inherited from class Object

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

- ## Field Details

  - ### NO_LIMIT

    public static final int NO_LIMIT
    Constant for a value representing no limit. If the limit is set to a value less or equal this constant, the `TimedSemaphore` will be effectively switched off.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### TimedSemaphore

    @Deprecated public TimedSemaphore(long timePeriod, TimeUnit timeUnit, int limit)
    Deprecated.
    Use `builder()` and `TimedSemaphore.Builder`.
    Constructs a new instance of `TimedSemaphore` and initializes it with the given time period and the limit.
    Parameters:
      `timePeriod` - the time period.
      `timeUnit` - the unit for the period.
      `limit` - the limit for the semaphore.
    Throws:
      `IllegalArgumentException` - if the period is less or equals 0.

  - ### TimedSemaphore

    @Deprecated public TimedSemaphore(ScheduledExecutorService service, long timePeriod, TimeUnit timeUnit, int limit)
    Deprecated.
    Use `builder()` and `TimedSemaphore.Builder`.
    Constructs a new instance of `TimedSemaphore` and initializes it with an executor service, the given time period, and the limit. The executor service will be used for creating a periodic task for monitoring the time period. It can be null, then a default service will be created.
    Parameters:
      `service` - the executor service.
      `timePeriod` - the time period.
      `timeUnit` - the unit for the period.
      `limit` - the limit for the semaphore.
    Throws:
      `IllegalArgumentException` - if the period is less or equals 0.

- ## Method Details

  - ### builder

    public static TimedSemaphore.Builder builder()
    Constructs a new Builder.
    Returns:
      a new Builder.
    Since:
      3.20.0

  - ### acquire

    public void acquire() throws InterruptedException
    Acquires a permit from this semaphore. This method will block if the limit for the current period has already been reached. If `shutdown()` has already been invoked, calling this method will cause an exception. The very first call of this method starts the timer task which monitors the time period set for this `TimedSemaphore`. From now on the semaphore is active.
    Throws:
      `InterruptedException` - if the thread gets interrupted.
      `IllegalStateException` - if this semaphore is already shut down.

  - ### getAcquireCount

    public int getAcquireCount()
    Gets the number of invocations of the `acquire()` method for the current period. This may be useful for testing or debugging purposes.
    Returns:
      the current number of `acquire()` invocations.

  - ### getAvailablePermits

    public int getAvailablePermits()
    Gets the number of calls to the `acquire()` method that can still be performed in the current period without blocking. This method can give an indication whether it is safe to call the `acquire()` method without risking to be suspended. However, there is no guarantee that a subsequent call to `acquire()` actually is not-blocking because in the meantime other threads may have invoked the semaphore.
    Returns:
      the current number of available `acquire()` calls in the current period.

  - ### getAverageCallsPerPeriod

    public double getAverageCallsPerPeriod()
    Gets the average number of successful (i.e. non-blocking) `acquire()` invocations for the entire life-time of this `TimedSemaphore`. This method can be used for instance for statistical calculations.
    Returns:
      the average number of `acquire()` invocations per time unit.

  - ### getExecutorService

    protected ScheduledExecutorService getExecutorService()
    Gets the executor service used by this instance.
    Returns:
      the executor service.

  - ### getLastAcquiresPerPeriod

    public int getLastAcquiresPerPeriod()
    Gets the number of (successful) acquire invocations during the last period. This is the number of times the `acquire()` method was called without blocking. This can be useful for testing or debugging purposes or to determine a meaningful threshold value. If a limit is set, the value returned by this method won't be greater than this limit.
    Returns:
      the number of non-blocking invocations of the `acquire()` method.

  - ### getLimit

    public final int getLimit()
    Gets the limit enforced by this semaphore. The limit determines how many invocations of `acquire()` are allowed within the monitored period.
    Returns:
      the limit.

  - ### getPeriod

    public long getPeriod()
    Gets the time period. This is the time monitored by this semaphore. Only a given number of invocations of the `acquire()` method is possible in this period.
    Returns:
      the time period.

  - ### getUnit

    public TimeUnit getUnit()
    Gets the time unit. This is the unit used by `getPeriod()`.
    Returns:
      the time unit.

  - ### isShutdown

    public boolean isShutdown()
    Tests whether the `shutdown()` method has been called on this object. If this method returns true, this instance cannot be used any longer.
    Returns:
      a flag whether a shutdown has been performed.

  - ### setLimit

    public final void setLimit(int limit)
    Sets the limit. This is the number of times the `acquire()` method can be called within the time period specified. If this limit is reached, further invocations of `acquire()` will block. Setting the limit to a value <= `NO_LIMIT` will cause the limit to be disabled, i.e. an arbitrary number of`acquire()` invocations is allowed in the time period.
    Parameters:
      `limit` - the limit.

  - ### shutdown

    public void shutdown()
    Initializes a shutdown. After that the object cannot be used anymore. This method can be invoked an arbitrary number of times. All invocations after the first one do not have any effect.

  - ### startTimer

    protected ScheduledFuture<?> startTimer()
    Starts the timer. This method is called when `acquire()` is called for the first time. It schedules a task to be executed at fixed rate to monitor the time period specified.
    Returns:
      a future object representing the task scheduled.

  - ### tryAcquire

    public boolean tryAcquire()
    Tries to acquire a permit from this semaphore. If the limit of this semaphore has not yet been reached, a permit is acquired, and this method returns true. Otherwise, this method returns immediately with the result false.
    Returns:
      true if a permit could be acquired; false otherwise.
    Throws:
      `IllegalStateException` - if this semaphore is already shut down.
    Since:
      3.5