Getting Started
Getting started with resilience4j-kotlin
Introduction
Integration for Kotlin coroutines that enables executing and decorating suspend
functions with the various resilience aspects provided by the core modules.
Extension functions that accept Kotlin suspend functions are provided for RateLimiter, Retry, CircuitBreaker, TimeLimiter, and semaphore-based Bulkheads. No extensions for ThreadPooBulkhead or Caches are currently provided.
Setup
Add the Kotlin module of Resilience4j to your compile dependency, along with whichever core modules are needed:
repositories {
jCenter()
}
dependencies {
compile "io.github.resilience4j:resilience4j-kotlin:${resilience4jVersion}"
// also have a dependency on the core module(s) needed - for example, retry:
compile "io.github.resilience4j:resilience4j-retry:${resilience4jVersion}"
}
Usage
Two extension functions are declared for each of CircuitBreaker
, RateLimiter
, Retry
, and TimeLimiter
: one to execute a suspend function, and one to decorate a suspend function.
val circuitBreaker = CircuitBreaker.ofDefaults()
val result = circuitBreaker.executeSuspendFunction {
// call suspending functions here
}
val function = circuitBreaker.decorateSuspendFunction {
// call suspending functions here
}
val result = function()
The suspend functions suspend where usage of the normal methods would block. For example, calls to a RateLimiter
which need to be delayed to fit within the rate limit suspend before the given function is executed.
No changes are made to the coroutine context of the given suspend functions.
Bulkhead
Decorating a suspend function with a Bulkhead
does not add any additional suspension points. If maxWaitTime
is non-zero, the call will block until the max wait time is reached or permission is obtained. For this reason, it is not recommended to use this extension function with Bulkheads with non-zero max wait times.
No extension functions for thread-pool based bulkheads are provided.
CircuitBreaker
Decorating a suspend function with a CircuitBreaker
does not add any additional suspension points.
Rate Limiter
Suspend functions decorated with a RateLimiter
use delay()
in order to suspend before executing the decorated function if the rate limit has been reached.
Retry
Suspend functions decorated with a Retry
use delay()
in order to suspend between retries.
Time Limiter
The TimeLimiter
extension functions simply use withTimeout()
from kotlinx-coroutines
, using the timeout from the receiver's configuration. Specifically, this means:
- On timeout, a
TimeoutCancellationException
is raised, rather than aTimeoutException
as with methods for non-suspending functions. - When a timeout occurs, the coroutine is cancelled, rather than the thread being interrupted as with methods for non-suspending functions.
- After the timeout, the given block can only be stopped at a cancellable suspending function call.
- The
cancelRunningFuture
configuration setting is ignored - on timeout, the suspend function is always cancelled even if thecancelRunningFuture
is set tofalse
.
Updated over 5 years ago