---
agentTools:
  projectIndex: https://resilience4j.readme.io/llms.txt
---

# RateLimiter

Getting started with resilience4j-ratelimiter

[block:api-header]
{
  "title": "Introduction"
}
[/block]

Rate limiting is an imperative technique to prepare your API for scale and establish high availability and reliability of your service. But also, this technique comes with a whole bunch of different options of how to handle a detected limits surplus, or what type of requests you want to limit. You can simply decline this over limit request, or build a queue to execute them later or combine these two approaches in some way.

## Internals

Resilience4j provides a RateLimiter which splits all nanoseconds from the start of epoch into cycles. Each cycle has a duration configured by `RateLimiterConfig.limitRefreshPeriod`. At the start of each cycle, the RateLimiter sets the number of active permissions to `RateLimiterConfig.limitForPeriod`.
For the RateLimiter callers it really looks like this, but for the `AtomicRateLimiter` implementation has some optimizations under the hood that will skip this refresh, if RateLimiter is not used actively.

[block:image]
{
  "images": [
    {
      "image": [
        "https://files.readme.io/44ca055-rate_limiter.png",
        "rate_limiter.png",
        1798,
        950,
        "#f5f1e4"
      ]
    }
  ]
}
[/block]

The default implementation of RateLimiter is `AtomicRateLimiter` which manages its state via AtomicReference. The AtomicRateLimiter.State is completely immutable and has the following fields:

* `activeCycle` - cycle number that was used by the last call
* `activePermissions` - count of available permissions after the last call.
  Can be negative if some permissions were reserved
* `nanosToWait` - count of nanoseconds to wait for permission for the last call

There is also a `SemaphoreBasedRateLimiter` which uses Semaphores and a scheduler that will refresh permissions after each `RateLimiterConfig#limitRefreshPeriod`.

[block:api-header]
{
  "title": "Create a RateLimiterRegistry"
}
[/block]

Just like the CircuitBreaker module, this module provides an in-memory `RateLimiterRegistry` which you can use to manage (create and retrieve) RateLimiter instances.

[block:code]
{
  "codes": [
    {
      "code": "RateLimiterRegistry rateLimiterRegistry = RateLimiterRegistry.ofDefaults();",
      "language": "java"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Create and configure a RateLimiter"
}
[/block]

You can provide a custom global RateLimiterConfig. In order to create a custom global RateLimiterConfig, you can use the RateLimiterConfig builder. You can use the builder to configure the following properties.

[block:parameters]
{
  "data": {
    "h-0": "Config property",
    "h-1": "Default value",
    "h-2": "Description",
    "0-0": "timeoutDuration",
    "1-0": "limitRefreshPeriod",
    "2-0": "limitForPeriod",
    "0-1": "5 [s]",
    "1-1": "500 [ns]",
    "2-1": "50",
    "0-2": "The default wait time a thread waits for a permission",
    "1-2": "The period of a limit refresh. After each period the rate limiter sets its permissions count back to the limitForPeriod value",
    "2-2": "The number of permissions available during one limit refresh period"
  },
  "cols": 3,
  "rows": 3
}
[/block]

For example, you want to restrict the calling rate of some methods to be not higher than 10 req/ms.

[block:code]
{
  "codes": [
    {
      "code": "RateLimiterConfig config = RateLimiterConfig.custom()\n  .limitRefreshPeriod(Duration.ofMillis(1))\n  .limitForPeriod(10)\n  .timeoutDuration(Duration.ofMillis(25))\n  .build();\n\n// Create registry\nRateLimiterRegistry rateLimiterRegistry = RateLimiterRegistry.of(config);\n\n// Use registry\nRateLimiter rateLimiterWithDefaultConfig = rateLimiterRegistry\n  .rateLimiter(\"name1\");\n\nRateLimiter rateLimiterWithCustomConfig = rateLimiterRegistry\n  .rateLimiter(\"name2\", config);",
      "language": "java"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Decorate and execute a functional interface"
}
[/block]

As you can guess RateLimiter has all sorts of higher-order decorator functions just like CircuitBreaker. You can decorate any `Callable`, `Supplier`, `Runnable`, `Consumer`, `CheckedRunnable`, `CheckedSupplier`, `CheckedConsumer` or `CompletionStage` with a RateLimiter .

[block:code]
{
  "codes": [
    {
      "code": "// Decorate your call to BackendService.doSomething()\nCheckedRunnable restrictedCall = RateLimiter\n    .decorateCheckedRunnable(rateLimiter, backendService::doSomething);\n\nTry.run(restrictedCall)\n    .andThenTry(restrictedCall)\n    .onFailure((RequestNotPermitted throwable) -> LOG.info(\"Wait before call it again :)\"));",
      "language": "java"
    }
  ]
}
[/block]

You can use changeTimeoutDuration and changeLimitForPeriod to change rate limiter params in runtime.
New timeout duration won’t affect threads that are currently waiting for permission.
The new limit won’t affect current period permissions and will apply only from the next one.

[block:code]
{
  "codes": [
    {
      "code": "// Decorate your call to BackendService.doSomething()\nCheckedRunnable restrictedCall = RateLimiter\n    .decorateCheckedRunnable(rateLimiter, backendService::doSomething);\n\n// during second refresh cycle limiter will get 100 permissions\nrateLimiter.changeLimitForPeriod(100);",
      "language": "java"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Consume emitted RegistryEvents"
}
[/block]

You can register event consumers on a RateLimiterRegistry and take actions whenever a RateLimiter is created, replaced, or deleted.

[block:code]
{
  "codes": [
    {
      "code": "RateLimiterRegistry registry = RateLimiterRegistry.ofDefaults();\nregistry.getEventPublisher()\n  .onEntryAdded(entryAddedEvent -> {\n    RateLimiter addedRateLimiter = entryAddedEvent.getAddedEntry();\n    LOG.info(\"RateLimiter {} added\", addedRateLimiter.getName());\n  })\n  .onEntryRemoved(entryRemovedEvent -> {\n    RateLimiter removedRateLimiter = entryRemovedEvent.getRemovedEntry();\n    LOG.info(\"RateLimiter {} removed\", removedRateLimiter.getName());\n  });",
      "language": "java"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Consume emitted RateLimiterEvents"
}
[/block]

The RateLimiter emits a stream of RateLimiterEvents. An event can be a successful permission acquire or acquire failure.
All events contain additional information like event creation time and rate limiter name.
If you want to consume events, you have to register as an event consumer.

[block:code]
{
  "codes": [
    {
      "code": "rateLimiter.getEventPublisher()\n    .onSuccess(event -> logger.info(...))\n    .onFailure(event -> logger.info(...));",
      "language": "java"
    }
  ]
}
[/block]

You can use RxJava, RxJava2 or Project Reactor Adapters to convert the EventPublisher into a Reactive Stream.

[block:code]
{
  "codes": [
    {
      "code": "ReactorAdapter.toFlux(rateLimiter.getEventPublisher())\n    .filter(event -> event.getEventType() == FAILED_ACQUIRE)\n    .subscribe(event -> logger.info(...))",
      "language": "java"
    }
  ]
}
[/block]

[block:api-header]
{
  "title": "Override the RegistryStore"
}
[/block]

You can override the in-memory RegistryStore by a custom implementation. For example, if you want to use a Cache that removes unused instances after a certain period of time.

[block:code]
{
  "codes": [
    {
      "code": "RateLimiterRegistry rateLimiterRegistry = RateLimiterRegistry.custom()\n  .withRegistryStore(new CacheRateLimiterRegistryStore())\n  .build();",
      "language": "java"
    }
  ]
}
[/block]