Join us on the livestream at Android Dev Summit on 7-8 November 2018, starting at 10AM PDT!

ContentRateLimiter

public class ContentRateLimiter
extends Object

java.lang.Object
   ↳ androidx.car.moderator.ContentRateLimiter


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.

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.

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.

Summary

Public constructors

ContentRateLimiter(double acquiredPermitsPerSecond, double maxStoredPermits, long fillDelayMs)

Creates a ContentRateLimiter with the given parameters.

Public methods

double getAvailablePermits()

Gets the current number of stored permits ready to be used.

double getMaxStoredPermits()

Gets the max number of permits allowed to be stored for future usage.

void setAcquiredPermitsRate(double acquiredPermitsPerSecond)

Sets the amount of permits that are acquired each second.

void setAvailablePermits(double availablePermits)

Sets the current number of stored permits that are ready to be used.

void setMaxStoredPermits(double maxStoredPermits)

The maximum amount of permits that can be stored.

void setPermitFillDelay(long fillDelayMs)

Sets delay before permits begin accumulating.

void setUnlimitedMode(boolean enabled)

Sets unlimited mode.

boolean tryAcquire()

Checks if there are enough available permits for a single permit to be acquired.

boolean tryAcquire(int permits)

Checks whether there are enough available permits to acquire.

Inherited methods

Public constructors

ContentRateLimiter

public ContentRateLimiter (double acquiredPermitsPerSecond, 
                double maxStoredPermits, 
                long fillDelayMs)

Creates a ContentRateLimiter with the given parameters.

Parameters
acquiredPermitsPerSecond double: The amount of permits that are acquired each second.

Value is 0.0 or greater.

maxStoredPermits double: The maximum number of permits that can be stored.

Value is 0.0 or greater.

fillDelayMs long: The amount of time to wait between when a permit is acquired and when the number of available permits start refilling.

Public methods

getAvailablePermits

public double getAvailablePermits ()

Gets the current number of stored permits ready to be used.

Returns
double

getMaxStoredPermits

public double getMaxStoredPermits ()

Gets the max number of permits allowed to be stored for future usage.

Returns
double

setAcquiredPermitsRate

public void setAcquiredPermitsRate (double acquiredPermitsPerSecond)

Sets the amount of permits that are acquired each second. These permits are acquired when the ContentRateLimiter is not being interacted with. That is, the tryAcquire() or tryAcquire(int) methods have not been called.

Parameters
acquiredPermitsPerSecond double: The number of permits acquired each second. Must be greater than zero.

Value is 0.0 or greater.

setAvailablePermits

public void setAvailablePermits (double availablePermits)

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.

Parameters
availablePermits double

setMaxStoredPermits

public void setMaxStoredPermits (double maxStoredPermits)

The maximum amount of permits that can be stored. Permits are accumulated when the the ContentRateLimiter is not being interacted with. That is, the tryAcquire() or tryAcquire(int) methods have not been called.

Parameters
maxStoredPermits double: The maximum number of stored permits. Must be greater than or equal to zero.

Value is 0.0 or greater.

setPermitFillDelay

public void setPermitFillDelay (long fillDelayMs)

Sets delay before permits begin accumulating. This is the delay after a tryAcquire() or tryAcquire(int) has been called. After the given delay, permits will be accumulated at the rate set by setAcquiredPermitsRate(double).

Parameters
fillDelayMs long: The delay in milliseconds before permits accumulate.

setUnlimitedMode

public void setUnlimitedMode (boolean enabled)

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.

Parameters
enabled boolean

tryAcquire

public boolean tryAcquire ()

Checks if there are enough available permits for a single permit to be acquired.

Returns
boolean true if unlimited mode is enabled or enough permits are acquirable at the time of this call; false if there isn't the number of permits requested available currently.

tryAcquire

public boolean tryAcquire (int permits)

Checks whether there are enough available permits to acquire.

Parameters
permits int

Returns
boolean true if unlimited mode is enabled or enough permits are acquirable at the time of this call; false if there isn't the number of permits requested available currently.