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 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 aach 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.
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.
| Modifier and Type | Field and Description |
|---|---|
static int |
NO_LIMIT
Constant for a value representing no limit.
|
| Constructor and Description |
|---|
TimedSemaphore(long timePeriod,
TimeUnit timeUnit,
int limit)
Creates a new instance of
TimedSemaphore and initializes it with
the given time period and the limit. |
TimedSemaphore(ScheduledExecutorService service,
long timePeriod,
TimeUnit timeUnit,
int limit)
Creates a new instance of
TimedSemaphore and initializes it with
an executor service, the given time period, and the limit. |
| Modifier and Type | Method and Description |
|---|---|
void |
acquire()
Tries to acquire a permit from this semaphore.
|
int |
getAcquireCount()
Returns the number of invocations of the
acquire() method for
the current period. |
int |
getAvailablePermits()
Returns the number of calls to the
acquire() method that can
still be performed in the current period without blocking. |
double |
getAverageCallsPerPeriod()
Returns the average number of successful (i.e. non-blocking)
acquire() invocations for the entire life-time of this TimedSemaphore. |
protected ScheduledExecutorService |
getExecutorService()
Returns the executor service used by this instance.
|
int |
getLastAcquiresPerPeriod()
Returns the number of (successful) acquire invocations during the last
period.
|
int |
getLimit()
Returns the limit enforced by this semaphore.
|
long |
getPeriod()
Returns the time period.
|
TimeUnit |
getUnit()
Returns the time unit.
|
boolean |
isShutdown()
Tests whether the
shutdown() method has been called on this
object. |
void |
setLimit(int limit)
Sets the limit.
|
void |
shutdown()
Initializes a shutdown.
|
protected ScheduledFuture<?> |
startTimer()
Starts the timer.
|
public static final int NO_LIMIT
TimedSemaphore will be
effectively switched off.public TimedSemaphore(long timePeriod, TimeUnit timeUnit, int limit)
TimedSemaphore and initializes it with
the given time period and the limit.timePeriod - the time periodtimeUnit - the unit for the periodlimit - the limit for the semaphoreIllegalArgumentException - if the period is less or equals 0public TimedSemaphore(ScheduledExecutorService service, long timePeriod, TimeUnit timeUnit, int limit)
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.service - the executor servicetimePeriod - the time periodtimeUnit - the unit for the periodlimit - the limit for the semaphoreIllegalArgumentException - if the period is less or equals 0public final int getLimit()
acquire() are allowed within the monitored
period.public final void setLimit(int limit)
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 ofacquire() invocations is allowed in
the time period.limit - the limitpublic void shutdown()
public boolean isShutdown()
shutdown() method has been called on this
object. If this method returns true, this instance cannot be used
any longer.public void acquire() throws InterruptedException
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.InterruptedException - if the thread gets interruptedIllegalStateException - if this semaphore is already shut downpublic int getLastAcquiresPerPeriod()
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.acquire()
methodpublic int getAcquireCount()
acquire() method for
the current period. This may be useful for testing or debugging purposes.acquire() invocationspublic int getAvailablePermits()
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 mean time other threads may have invoked the semaphore.acquire() calls in the
current periodpublic double getAverageCallsPerPeriod()
acquire() invocations for the entire life-time of this TimedSemaphore. This method can be used for instance for statistical
calculations.acquire() invocations per time
unitpublic long getPeriod()
acquire() method is
possible in this period.public TimeUnit getUnit()
getPeriod().protected ScheduledExecutorService getExecutorService()
protected ScheduledFuture<?> startTimer()
acquire() is called
for the first time. It schedules a task to be executed at fixed rate to
monitor the time period specified.Copyright © 2001–2015 The Apache Software Foundation. All rights reserved.