Class FixedRateBarrier
- java.lang.Object
-
- com.unboundid.util.FixedRateBarrier
-
- All Implemented Interfaces:
java.io.Serializable
@ThreadSafety(level=COMPLETELY_THREADSAFE) public final class FixedRateBarrier extends java.lang.Object implements java.io.Serializable
Instances of this class are used to ensure that certain actions are performed at a fixed rate per interval (e.g. 10000 search operations per second).Once a class is constructed with the duration of an interval and the target per interval, the
await()
method only releases callers at the specified number of times per interval. This class is most useful when the target number per interval exceeds the limits of other approaches such asjava.util.Timer
orjava.util.concurrent.ScheduledThreadPoolExecutor
. For instance, this does a good job of ensuring that something happens about 10000 times per second, but it's overkill to ensure something happens five times per hour. This does come at a cost. In the worst case, a single thread is tied up in a loop doing a small amount of computation followed by a Thread.yield(). Calling Thread.sleep() is not possible because many platforms sleep for a minimum of 10ms, and all platforms require sleeping for at least 1ms.Testing has shown that this class is accurate for a "no-op" action up to two million per second, which vastly exceeds its typical use in tools such as
searchrate
andmodrate
. This class is designed to be called by multiple threads, however, it does not make any fairness guarantee between threads; a single-thread might be released from theawait()
method many times before another thread that is blocked in that method.This class attempts to smooth out the target per interval throughout each interval. At a given ratio, R between 0 and 1, through the interval, the expected number of actions to have been performed in the interval at that time is R times the target per interval. That is, 10% of the way through the interval, approximately 10% of the actions have been performed, and 80% of the way through the interval, 80% of the actions have been performed.
It's possible to wait for multiple "actions" in one call with
await(int)
. An example use is rate limiting writing bytes out to a file. You could configure a FixedRateBarrier to only allow 1M bytes to be written per second, and then callawait(int)
with the size of the byte buffer to write. The call toawait(int)
would block until writing out the buffer would not exceed the desired rate.- See Also:
- Serialized Form
-
-
Constructor Summary
Constructors Constructor Description FixedRateBarrier(long intervalDurationMs, int perInterval)
Constructs a new FixedRateBarrier, which is active untilshutdownRequested
is called.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description boolean
await()
This method waits until it is time for the next 'action' to be performed based on the specified interval duration and target per interval.boolean
await(int count)
This method waits until it is time for the nextcount
'actions' to be performed based on the specified interval duration and target per interval.ObjectPair<java.lang.Long,java.lang.Integer>
getTargetRate()
Retrieves information about the current target rate for this barrier.boolean
isShutdownRequested()
Returnstrue
if shutdown has been requested.void
setRate(long intervalDurationMs, int perInterval)
Updates the rates associated with this FixedRateBarrier.void
shutdownRequested()
Shuts down this barrier.
-
-
-
Constructor Detail
-
FixedRateBarrier
public FixedRateBarrier(long intervalDurationMs, int perInterval)
Constructs a new FixedRateBarrier, which is active untilshutdownRequested
is called.- Parameters:
intervalDurationMs
- The duration of the interval in milliseconds.perInterval
- The target number of times thatawait()
should return per interval.
-
-
Method Detail
-
setRate
public void setRate(long intervalDurationMs, int perInterval)
Updates the rates associated with this FixedRateBarrier. The new rate will be in effect when this method returns.- Parameters:
intervalDurationMs
- The duration of the interval in milliseconds.perInterval
- The target number of times thatawait()
should return per interval.
-
await
public boolean await()
This method waits until it is time for the next 'action' to be performed based on the specified interval duration and target per interval. This method can be called by multiple threads simultaneously. This method returns immediately if shutdown has been requested.- Returns:
true
if shutdown has been requested and false otherwise.
-
await
public boolean await(int count)
This method waits until it is time for the nextcount
'actions' to be performed based on the specified interval duration and target per interval. To achieve the target rate, it's recommended that on averagecount
is small relative toperInterval
(and thecount
must not be larger thanperInterval
). Acount
value will not be split across intervals, and due to timing issues, it's possible that acount
that barely fits in the current interval will need to wait until the next interval. If it's not possible to use smaller 'count' values, then increaseperInterval
andintervalDurationMs
by the same relative amount. As an example, ifcount
is on average 1/10 as big asperInterval
, then you can expect to attain 90% of the target rate. IncreasingperInterval
andintervalDurationMs
by 10x means that 99% of the target rate can be achieved.This method can be called by multiple threads simultaneously. This method returns immediately if shutdown has been requested.
- Parameters:
count
- The number of 'actions' being performed. It must be less than or equal toperInterval
, and is recommended to be fairly small relative toperInterval
so that it is easier to achieve the desired rate and exhibit smoother performance.- Returns:
true
if shutdown has been requested and false otherwise.
-
getTargetRate
@NotNull public ObjectPair<java.lang.Long,java.lang.Integer> getTargetRate()
Retrieves information about the current target rate for this barrier. The value returned will include aLong
that specifies the duration of the current interval in milliseconds and anInteger
that specifies the number of times that theawait()
method should return per interval.- Returns:
- Information about hte current target rate for this barrier.
-
shutdownRequested
public void shutdownRequested()
Shuts down this barrier. Future calls to await() will return immediately.
-
isShutdownRequested
public boolean isShutdownRequested()
Returnstrue
if shutdown has been requested.- Returns:
true
if shutdown has been requested andfalse
otherwise.
-
-