/*
* Copyright (C) 2018 The Android Open Source Project
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package androidx.car.moderator;
import static java.util.concurrent.TimeUnit.SECONDS;
import android.util.Log;
import androidx.annotation.FloatRange;
import androidx.annotation.IntRange;
import androidx.annotation.MainThread;
import androidx.annotation.VisibleForTesting;
import androidx.core.util.Preconditions;
/**
* A class that keeps track of a general number of permitted actions that happen over time and
* determines if a subsequent interaction is allowed. The type of interaction is arbitrary and not
* transparent to this class. Instead, it will refer to these actions as "permits," short for
* "permitted action." It is up to a user of this class to determine the unit of permits.
*
* <p>This class allows for two quick acquires in succession to only consume one permit. This is
* intended behavior to account for the fact that the user can be using many taps to scroll
* quickly. This can fit within the window for which a user does not necessary have their eyes
* off the road for a long period of time, and thus should not be penalized.
*
* <p>This class allows for the maximum number of permits that can be stored,the amount of permits
* that are filled each second, as well as the delay before re-fill to be configured.
*/
public class ContentRateLimiter {
private static final String TAG = "ContentRateLimiter";
/** The maximum number of stored permits. */
private double mMaxStoredPermits;
/**
* The interval between two unit requests at our stable rate. For example, a stable rate of
* 5 permits per second has a stable interval of 200ms.
*/
private long mStableIntervalMs;
/**
* The amount of time to wait between when a permit is acquired and when the model starts
* refilling.
*/
private long mFillDelayMs;
/** Unlimited mode. Once enabled, any number of permits can be acquired and consumed. */
private boolean mUnlimitedModeEnabled;
/**
* Used to do incremental calculations by {@link #getLastCalculatedPermitCount()}, cannot be
* used directly.
*/
private double mLastCalculatedPermitCount;
/** Time in milliseconds when permits can resume incrementing. */
private long mResumeIncrementingMs;
/** Tracks if the model will allow a second permit to be requested in the fill delay. */
private boolean mSecondaryFillDelayPermitAvailable = true;
private final ElapsedTimeProvider mElapsedTimeProvider;
/**
* An interface for a provider of the current time that has passed since boot. This interface
* is meant to abstract the {@link android.os.SystemClock} so that it can be mocked during
* testing.
*/
interface ElapsedTimeProvider {
/** Returns milliseconds since boot, including time spent in sleep. */
long getElapsedRealtime();
}
/**
* Creates a {@code ContentRateLimiter} with the given parameters.
*
* @param acquiredPermitsPerSecond The amount of permits that are acquired each second.
* @param maxStoredPermits The maximum number of permits that can be stored.
* @param fillDelayMs The amount of time to wait between when a permit is acquired and when
* the number of available permits start refilling.
*/
public ContentRateLimiter(
@FloatRange(from = 0, fromInclusive = false) double acquiredPermitsPerSecond,
@FloatRange(from = 0) double maxStoredPermits,
@IntRange(from = 0) long fillDelayMs) {
this(acquiredPermitsPerSecond, maxStoredPermits, fillDelayMs,
new SystemClockTimeProvider());
}
// A constructor that allows for the SystemClockTimeProvider to be provided. This is needed for
// testing so that the unit test does not rely on the actual SystemClock.
@VisibleForTesting
ContentRateLimiter(
@FloatRange(from = 0, fromInclusive = false) double acquiredPermitsPerSecond,
@FloatRange(from = 0) double maxStoredPermits,
@IntRange(from = 0) long fillDelayMs,
ElapsedTimeProvider elapsedTimeProvider) {
mElapsedTimeProvider = elapsedTimeProvider;
mResumeIncrementingMs = mElapsedTimeProvider.getElapsedRealtime();
setAcquiredPermitsRate(acquiredPermitsPerSecond);
setMaxStoredPermits(maxStoredPermits);
setPermitFillDelay(fillDelayMs);
if (Log.isLoggable(TAG, Log.VERBOSE)) {
Log.v(TAG, String.format("permitsPerSecond: %f maxStoredPermits: %f, fillDelayMs %d",
acquiredPermitsPerSecond, maxStoredPermits, fillDelayMs));
}
}
/**
* Sets the amount of permits that are acquired each second. These permits are acquired when
* the {@code ContentRateLimiter} is not being interacted with. That is, the
* {@link #tryAcquire()} or {@link #tryAcquire(int)} methods have not been called.
*
* @param acquiredPermitsPerSecond The number of permits acquired each second. Must be greater
* than zero.
*/
public void setAcquiredPermitsRate(
@FloatRange(from = 0, fromInclusive = false) double acquiredPermitsPerSecond) {
Preconditions.checkArgument(acquiredPermitsPerSecond > 0);
mStableIntervalMs = (long) (SECONDS.toMillis(1L) / acquiredPermitsPerSecond);
}
/**
* The maximum amount of permits that can be stored. Permits are accumulated when the
* the {@code ContentRateLimiter} is not being interacted with. That is, the
* {@link #tryAcquire()} or {@link #tryAcquire(int)} methods have not been called.
*
* @param maxStoredPermits The maximum number of stored permits. Must be greater than or equal
* to zero.
*/
public void setMaxStoredPermits(@FloatRange(from = 0) double maxStoredPermits) {
Preconditions.checkArgument(maxStoredPermits >= 0);
mMaxStoredPermits = maxStoredPermits;
mLastCalculatedPermitCount = maxStoredPermits;
}
/**
* Sets delay before permits begin accumulating. This is the delay after a {@link #tryAcquire()}
* or {@link #tryAcquire(int)} has been called. After the given delay, permits will be
* accumulated at the rate set by {@link #setAcquiredPermitsRate(double)}.
*
* @param fillDelayMs The delay in milliseconds before permits accumulate.
*/
public void setPermitFillDelay(@IntRange(from = 0) long fillDelayMs) {
Preconditions.checkArgument(fillDelayMs >= 0);
mFillDelayMs = fillDelayMs;
}
/** Gets the current number of stored permits ready to be used. */
@MainThread
public double getAvailablePermits() {
return getLastCalculatedPermitCount();
}
/**
* Sets the current number of stored permits that are ready to be used. If this value exceeds
* the maximum number of stored permits that is passed to the constructor, then the max value
* is used instead.
*/
@MainThread
public void setAvailablePermits(double availablePermits) {
setLastCalculatedPermitCount(availablePermits, mElapsedTimeProvider.getElapsedRealtime());
}
/** Gets the max number of permits allowed to be stored for future usage. */
public double getMaxStoredPermits() {
return mMaxStoredPermits;
}
/**
* Checks if there are enough available permits for a single permit to be acquired.
*
* @return {@code true} if unlimited mode is enabled or enough permits are acquirable at the
* time of this call; {@code false} if there isn't the number of permits requested available
* currently.
*/
@MainThread
public boolean tryAcquire() {
return tryAcquire(1);
}
/**
* Checks whether there are enough available permits to acquire.
*
* @return {@code true} if unlimited mode is enabled or enough permits are acquirable at the
* time of this call; {@code false} if there isn't the number of permits requested available
* currently.
*/
@MainThread
public boolean tryAcquire(int permits) {
// Once unlimited mode is enabled, we can acquire any number of permits we want and don't
// consume the stored permits.
if (mUnlimitedModeEnabled) {
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "Unlimited mode is enabled.");
}
return true;
}
double availablePermits = getLastCalculatedPermitCount();
long nowMs = mElapsedTimeProvider.getElapsedRealtime();
if (Log.isLoggable(TAG, Log.VERBOSE)) {
Log.v(TAG, String.format("Requesting: %d, Stored: %f/%f", permits,
mLastCalculatedPermitCount, mMaxStoredPermits));
}
if (availablePermits <= permits) {
// Once locked out, the user is prevented from acquiring any more permits until they
// have waited long enough for a permit to refill. If the user attempts to acquire a
// permit during this time, the countdown timer until a permit is refilled is reset.
setLastCalculatedPermitCount(0, nowMs + mFillDelayMs);
return false;
} else if (nowMs < mResumeIncrementingMs && mSecondaryFillDelayPermitAvailable) {
// If a second permit is requested between the time a first permit was requested and
// the fill delay, allow the second permit to be acquired without decrementing the model
// and set the point where permits can resume incrementing {@link #mFillDelayMs} in the
// future.
setLastCalculatedPermitCount(availablePermits, nowMs + mFillDelayMs);
// Don't allow a third "free" permit to be acquired in the fill delay fringe.
mSecondaryFillDelayPermitAvailable = false;
if (Log.isLoggable(TAG, Log.DEBUG)) {
Log.d(TAG, "Used up free secondary permit");
}
return true;
} else {
// Decrement the available permits, and set the point where permits can resume
// incrementing {@link #mFillDelayMs} in the future.
setLastCalculatedPermitCount(availablePermits - permits, nowMs + mFillDelayMs);
if (Log.isLoggable(TAG, Log.VERBOSE)) {
Log.v(TAG, String.format("permits remaining %s, secondary permit available %s",
mLastCalculatedPermitCount,
mSecondaryFillDelayPermitAvailable));
}
mSecondaryFillDelayPermitAvailable = true;
return true;
}
}
/**
* Sets unlimited mode. If enabled, there is no restriction on the number of permits that
* can be acquired and any interaction does not consume stored permits.
*/
public void setUnlimitedMode(boolean enabled) {
mUnlimitedModeEnabled = enabled;
}
/**
* Updates {@link #mLastCalculatedPermitCount} and {@link #mResumeIncrementingMs} based on the
* current time.
*/
private double getLastCalculatedPermitCount() {
long nowMs = mElapsedTimeProvider.getElapsedRealtime();
if (nowMs > mResumeIncrementingMs) {
long deltaMs = nowMs - mResumeIncrementingMs;
double newPermits = deltaMs / (double) mStableIntervalMs;
setLastCalculatedPermitCount(mLastCalculatedPermitCount + newPermits, nowMs);
}
return mLastCalculatedPermitCount;
}
private void setLastCalculatedPermitCount(double newCount, long nextMs) {
mLastCalculatedPermitCount = Math.min(mMaxStoredPermits, newCount);
mResumeIncrementingMs = nextMs;
}
}