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:

Groovy

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.

Kotlin

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 a TimeoutException 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 the cancelRunningFuture is set to false.