A specialized semaphore implementation that provides a number of permits in a given time frame.

This class is similar to the java.util.concurrent.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.