Class SemaphoreBasedRateLimiter

java.lang.Object

io.github.resilience4j.ratelimiter.internal.SemaphoreBasedRateLimiter

All Implemented Interfaces:

RateLimiter

public class SemaphoreBasedRateLimiter
extends Object
implements RateLimiter

A RateLimiter implementation that consists of Semaphore and scheduler that will refresh permissions after each RateLimiterConfig.getLimitRefreshPeriod(), you can invoke shutdown() to close the limiter.

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
private final class	SemaphoreBasedRateLimiter.SemaphoreBasedRateLimiterMetrics

Nested classes/interfaces inherited from interface RateLimiter

RateLimiter.EventPublisher, RateLimiter.Metrics

Field Summary

Fields

Modifier and Type	Field	Description
private static final String	CONFIG_MUST_NOT_BE_NULL
private final RateLimiterEventProcessor	eventProcessor
private final SemaphoreBasedRateLimiter.SemaphoreBasedRateLimiterMetrics	metrics
private final String	name
private static final String	NAME_MUST_NOT_BE_NULL
private final AtomicReference<RateLimiterConfig>	rateLimiterConfig
private final ScheduledFuture<?>	scheduledFuture
private final ScheduledExecutorService	scheduler
private final Semaphore	semaphore
private final Map<String,String>	tags

Constructor Summary

Constructors

Constructor	Description
SemaphoreBasedRateLimiter(String name, RateLimiterConfig rateLimiterConfig)	Creates a RateLimiter.
SemaphoreBasedRateLimiter(String name, RateLimiterConfig rateLimiterConfig, ScheduledExecutorService scheduler)	Creates a RateLimiter.
SemaphoreBasedRateLimiter(String name, RateLimiterConfig rateLimiterConfig, ScheduledExecutorService scheduler, Map<String,String> tags)	Creates a RateLimiter.
SemaphoreBasedRateLimiter(String name, RateLimiterConfig rateLimiterConfig, Map<String,String> tags)	Creates a RateLimiter.

Method Summary

Modifier and Type	Method	Description
boolean	acquirePermission(int permits)	Acquires the given number of permits from this rate limiter, blocking until one is available, or the thread is interrupted.
void	changeLimitForPeriod(int limitForPeriod)	Dynamic rate limiter configuration change.
void	changeTimeoutDuration(Duration timeoutDuration)	Dynamic rate limiter configuration change.
private ScheduledExecutorService	configureScheduler()
void	drainPermissions()	Drains all the permits left in the current period.
RateLimiter.EventPublisher	getEventPublisher()	Returns an EventPublisher which can be used to register event consumers.
RateLimiter.Metrics	getMetrics()	Get the Metrics of this RateLimiter.
String	getName()	Get the name of this RateLimiter
RateLimiterConfig	getRateLimiterConfig()	Get the RateLimiterConfig of this RateLimiter.
Map<String,String>	getTags()	Returns an unmodifiable map with tags assigned to this RateLimiter.
private void	publishRateLimiterAcquisitionEvent(boolean permissionAcquired, int permits)
(package private) void	refreshLimit()
long	reservePermission()	Reserving permissions is not supported in the semaphore based implementation.
long	reservePermission(int permits)	Reserves the given number permits from this rate limiter and returns nanoseconds you should wait for it.
private ScheduledFuture<?>	scheduleLimitRefresh()
void	shutdown()	Close the scheduled task that refresh permissions if you don't use the SemaphoreBasedRateLimiter anymore.
String	toString()

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface RateLimiter

acquirePermission, drainIfNeeded, executeCallable, executeCallable, executeCheckedSupplier, executeCheckedSupplier, executeCompletionStage, executeRunnable, executeRunnable, executeSupplier, executeSupplier, onError, onResult, onSuccess

Field Details

NAME_MUST_NOT_BE_NULL

private static final String NAME_MUST_NOT_BE_NULL

See Also:

• Constant Field Values

CONFIG_MUST_NOT_BE_NULL

private static final String CONFIG_MUST_NOT_BE_NULL

See Also:

• Constant Field Values

name

private final String name

rateLimiterConfig

private final AtomicReference<RateLimiterConfig> rateLimiterConfig

scheduler

private final ScheduledExecutorService scheduler

semaphore

private final Semaphore semaphore

metrics

private final SemaphoreBasedRateLimiter.SemaphoreBasedRateLimiterMetrics metrics

tags

private final Map<String,String> tags

eventProcessor

private final RateLimiterEventProcessor eventProcessor

scheduledFuture

private final ScheduledFuture<?> scheduledFuture

Constructor Details

SemaphoreBasedRateLimiter

public SemaphoreBasedRateLimiter(String name,
 RateLimiterConfig rateLimiterConfig)

Creates a RateLimiter.

Parameters:

name - the name of the RateLimiter

rateLimiterConfig - The RateLimiter configuration.

SemaphoreBasedRateLimiter

public SemaphoreBasedRateLimiter(String name,
 RateLimiterConfig rateLimiterConfig,
 Map<String,String> tags)

Creates a RateLimiter.

Parameters:

name - the name of the RateLimiter

rateLimiterConfig - The RateLimiter configuration.

tags - tags to assign to the RateLimiter

SemaphoreBasedRateLimiter

public SemaphoreBasedRateLimiter(String name,
 RateLimiterConfig rateLimiterConfig,
 @Nullable
 ScheduledExecutorService scheduler)

Creates a RateLimiter.

Parameters:

name - the name of the RateLimiter

rateLimiterConfig - The RateLimiter configuration.

scheduler - executor that will refresh permissions

SemaphoreBasedRateLimiter

public SemaphoreBasedRateLimiter(String name,
 RateLimiterConfig rateLimiterConfig,
 @Nullable
 ScheduledExecutorService scheduler,
 Map<String,String> tags)

Creates a RateLimiter.

Parameters:

name - the name of the RateLimiter

rateLimiterConfig - The RateLimiter configuration.

scheduler - executor that will refresh permissions

tags - tags to assign to the RateLimiter

Method Details

configureScheduler

private ScheduledExecutorService configureScheduler()

scheduleLimitRefresh

private ScheduledFuture<?> scheduleLimitRefresh()

refreshLimit

void refreshLimit()

changeTimeoutDuration

public void changeTimeoutDuration(Duration timeoutDuration)

Dynamic rate limiter configuration change. This method allows to change timeout duration of current limiter. NOTE! New timeout duration won't affect threads that are currently waiting for permission.

Specified by:

changeTimeoutDuration in interface RateLimiter

Parameters:

timeoutDuration - new timeout duration

changeLimitForPeriod

public void changeLimitForPeriod(int limitForPeriod)

Dynamic rate limiter configuration change. This method allows to change count of permissions available during refresh period. NOTE! New limit won't affect current period permissions and will apply only from next one.

Specified by:

changeLimitForPeriod in interface RateLimiter

Parameters:

limitForPeriod - new permissions limit

acquirePermission

public boolean acquirePermission(int permits)

Acquires the given number of permits from this rate limiter, blocking until one is available, or the thread is interrupted. Maximum wait time is RateLimiterConfig.getTimeoutDuration()

If the current thread is interrupted while waiting for a permit then it won't throw InterruptedException, but its interrupt status will be set.

Specified by:

acquirePermission in interface RateLimiter

Parameters:

permits - number of permits - use for systems where 1 call != 1 permit

Returns:

true if a permit was acquired and false if waiting timeoutDuration elapsed before a permit was acquired

reservePermission

public long reservePermission()

Reserving permissions is not supported in the semaphore based implementation. Semaphores are totally blocking by it's nature. So this non-blocking API isn't supported. Use RateLimiter.acquirePermission()

Specified by:

reservePermission in interface RateLimiter

Returns:

long amount of nanoseconds you should wait for reserved permissions. if negative, it means you failed to reserve.

Throws:

UnsupportedOperationException - always for this implementation

reservePermission

public long reservePermission(int permits)

Description copied from interface: RateLimiter

Reserves the given number permits from this rate limiter and returns nanoseconds you should wait for it. If returned long is negative, it means that you failed to reserve permission, possibly your RateLimiterConfig.getTimeoutDuration() is less then time to wait for permission.

Specified by:

reservePermission in interface RateLimiter

Parameters:

permits - number of permits - use for systems where 1 call != 1 permit

Returns:

long amount of nanoseconds you should wait for reserved permissions. if negative, it means you failed to reserve.

Throws:

UnsupportedOperationException - always for this implementation

See Also:

• reservePermission()

drainPermissions

public void drainPermissions()

Description copied from interface: RateLimiter

Drains all the permits left in the current period.

Specified by:

drainPermissions in interface RateLimiter

getName

public String getName()

Get the name of this RateLimiter

Specified by:

getName in interface RateLimiter

Returns:

the name of this RateLimiter

getMetrics

public RateLimiter.Metrics getMetrics()

Get the Metrics of this RateLimiter.

Specified by:

getMetrics in interface RateLimiter

Returns:

the Metrics of this RateLimiter

getEventPublisher

public RateLimiter.EventPublisher getEventPublisher()

Description copied from interface: RateLimiter

Returns an EventPublisher which can be used to register event consumers.

Specified by:

getEventPublisher in interface RateLimiter

Returns:

an EventPublisher

getRateLimiterConfig

public RateLimiterConfig getRateLimiterConfig()

Get the RateLimiterConfig of this RateLimiter.

Specified by:

getRateLimiterConfig in interface RateLimiter

Returns:

the RateLimiterConfig of this RateLimiter

toString

public String toString()

Overrides:

toString in class Object

getTags

public Map<String,String> getTags()

Description copied from interface: RateLimiter

Returns an unmodifiable map with tags assigned to this RateLimiter.

Specified by:

getTags in interface RateLimiter

Returns:

the tags assigned to this Retry in an unmodifiable map

publishRateLimiterAcquisitionEvent

private void publishRateLimiterAcquisitionEvent(boolean permissionAcquired,
 int permits)

shutdown

public void shutdown()

Close the scheduled task that refresh permissions if you don't use the SemaphoreBasedRateLimiter anymore. Otherwise, the SemaphoreBasedRateLimiter instance will not be garbage collected even if you hold the reference, meaning if you create millions of instance, there could be a memory leak. (https://github.com/resilience4j/resilience4j/issues/1683)