Package io.github.resilience4j.bulkhead

Interface Bulkhead

All Known Implementing Classes:
SemaphoreBulkhead
public interface Bulkhead
A Bulkhead instance is thread-safe can be used to decorate multiple requests.

A Bulkhead represent an entity limiting the amount of parallel operations. It does not assume nor does it mandate usage of any particular concurrency and/or io model. These details are left for the client to manage. This bulkhead, depending on the underlying concurrency/io model can be used to shed load, and, where it makes sense, limit resource use (i.e. limit amount of threads/actors involved in a particular flow, etc).

In order to execute an operation protected by this bulkhead, a permission must be obtained by calling tryAcquirePermission() ()} If the bulkhead is full, no additional operations will be permitted to execute until space is available.

Once the operation is complete, regardless of the result, client needs to call onComplete() in order to maintain integrity of internal bulkhead state.

  • Nested Class Summary

    Nested Classes 
    Modifier and Type Interface Description
    static class  Bulkhead.BulkheadFuture<T>
    This class decorates future with Bulkhead functionality around invocation.
    static interface  Bulkhead.EventPublisher
    An EventPublisher which can be used to register event consumers.
    static interface  Bulkhead.Metrics  

  • Method Summary

    Modifier and Type Method Description
    void acquirePermission()
    Acquires a permission to execute a call, only if one is available at the time of invocation If the current thread is interrupted while waiting for a permit then it won't throw InterruptedException, but its interrupt status will be set.
    void changeConfig​(BulkheadConfig newConfig)
    Dynamic bulkhead configuration change.
    static <T> java.util.concurrent.Callable<T> decorateCallable​(Bulkhead bulkhead, java.util.concurrent.Callable<T> callable)
    Returns a callable which is decorated by a bulkhead.
    static <T> io.vavr.CheckedConsumer<T> decorateCheckedConsumer​(Bulkhead bulkhead, io.vavr.CheckedConsumer<T> consumer)
    Returns a consumer which is decorated by a bulkhead.
    static <T,​ R> io.vavr.CheckedFunction1<T,​R> decorateCheckedFunction​(Bulkhead bulkhead, io.vavr.CheckedFunction1<T,​R> function)
    Returns a function which is decorated by a bulkhead.
    static io.vavr.CheckedRunnable decorateCheckedRunnable​(Bulkhead bulkhead, io.vavr.CheckedRunnable runnable)
    Returns a runnable which is decorated by a bulkhead.
    static <T> io.vavr.CheckedFunction0<T> decorateCheckedSupplier​(Bulkhead bulkhead, io.vavr.CheckedFunction0<T> supplier)
    Returns a supplier which is decorated by a bulkhead.
    static <T> java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> decorateCompletionStage​(Bulkhead bulkhead, java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
    Returns a supplier which is decorated by a bulkhead.
    static <T> java.util.function.Consumer<T> decorateConsumer​(Bulkhead bulkhead, java.util.function.Consumer<T> consumer)
    Returns a consumer which is decorated by a bulkhead.
    static <T> java.util.function.Supplier<io.vavr.control.Either<java.lang.Exception,​T>> decorateEitherSupplier​(Bulkhead bulkhead, java.util.function.Supplier<io.vavr.control.Either<? extends java.lang.Exception,​T>> supplier)
    Returns a supplier which is decorated by a bulkhead.
    static <T,​ R> java.util.function.Function<T,​R> decorateFunction​(Bulkhead bulkhead, java.util.function.Function<T,​R> function)
    Returns a function which is decorated by a bulkhead.
    static <T> java.util.function.Supplier<java.util.concurrent.Future<T>> decorateFuture​(Bulkhead bulkhead, java.util.function.Supplier<java.util.concurrent.Future<T>> supplier)
    Returns a supplier of type Future which is decorated by a bulkhead.
    static java.lang.Runnable decorateRunnable​(Bulkhead bulkhead, java.lang.Runnable runnable)
    Returns a runnable which is decorated by a bulkhead.
    static <T> java.util.function.Supplier<T> decorateSupplier​(Bulkhead bulkhead, java.util.function.Supplier<T> supplier)
    Returns a supplier which is decorated by a bulkhead.
    static <T> java.util.function.Supplier<io.vavr.control.Try<T>> decorateTrySupplier​(Bulkhead bulkhead, java.util.function.Supplier<io.vavr.control.Try<T>> supplier)
    Returns a supplier which is decorated by a bulkhead.
    default <T> T executeCallable​(java.util.concurrent.Callable<T> callable)
    Decorates and executes the decorated Callable.
    default <T> T executeCheckedSupplier​(io.vavr.CheckedFunction0<T> checkedSupplier)
    Decorates and executes the decorated Supplier.
    default <T> java.util.concurrent.CompletionStage<T> executeCompletionStage​(java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
    Decorates and executes the decorated CompletionStage.
    default <T> io.vavr.control.Either<java.lang.Exception,​T> executeEitherSupplier​(java.util.function.Supplier<io.vavr.control.Either<? extends java.lang.Exception,​T>> supplier)
    Decorates and executes the decorated Supplier.
    default void executeRunnable​(java.lang.Runnable runnable)
    Decorates and executes the decorated Runnable.
    default <T> T executeSupplier​(java.util.function.Supplier<T> supplier)
    Decorates and executes the decorated Supplier.
    default <T> io.vavr.control.Try<T> executeTrySupplier​(java.util.function.Supplier<io.vavr.control.Try<T>> supplier)
    Decorates and executes the decorated Supplier.
    BulkheadConfig getBulkheadConfig()
    Returns the BulkheadConfig of this Bulkhead.
    Bulkhead.EventPublisher getEventPublisher()
    Returns an EventPublisher which subscribes to the reactive stream of BulkheadEvent and can be used to register event consumers.
    Bulkhead.Metrics getMetrics()
    Get the Metrics of this Bulkhead.
    java.lang.String getName()
    Returns the name of this bulkhead.
    io.vavr.collection.Map<java.lang.String,​java.lang.String> getTags()
    Returns an unmodifiable map with tags assigned to this Bulkhead.
    static Bulkhead of​(java.lang.String name, BulkheadConfig config)
    Creates a bulkhead with a custom configuration
    static Bulkhead of​(java.lang.String name, BulkheadConfig config, io.vavr.collection.Map<java.lang.String,​java.lang.String> tags)
    Creates a bulkhead with a custom configuration
    static Bulkhead of​(java.lang.String name, java.util.function.Supplier<BulkheadConfig> bulkheadConfigSupplier)
    Creates a bulkhead with a custom configuration
    static Bulkhead of​(java.lang.String name, java.util.function.Supplier<BulkheadConfig> bulkheadConfigSupplier, io.vavr.collection.Map<java.lang.String,​java.lang.String> tags)
    Creates a bulkhead with a custom configuration
    static Bulkhead ofDefaults​(java.lang.String name)
    Create a Bulkhead with a default configuration.
    void onComplete()
    Records a completed call and releases a permission.
    void releasePermission()
    Releases a permission and increases the number of available permits by one.
    boolean tryAcquirePermission()
    Acquires a permission to execute a call, only if one is available at the time of invocation.

  • Method Details

    • decorateCheckedSupplier

      static <T> io.vavr.CheckedFunction0<T> decorateCheckedSupplier​(Bulkhead bulkhead, io.vavr.CheckedFunction0<T> supplier)
      Returns a supplier which is decorated by a bulkhead.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      bulkhead - the Bulkhead
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateCompletionStage

      static <T> java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> decorateCompletionStage​(Bulkhead bulkhead, java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
      Returns a supplier which is decorated by a bulkhead.
      Type Parameters:
      T - the type of the returned CompletionStage's result
      Parameters:
      bulkhead - the bulkhead
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateFuture

      static <T> java.util.function.Supplier<java.util.concurrent.Future<T>> decorateFuture​(Bulkhead bulkhead, java.util.function.Supplier<java.util.concurrent.Future<T>> supplier)
      Returns a supplier of type Future which is decorated by a bulkhead. Bulkhead will reserve permission until Future.get() or Future.get(long, TimeUnit) is evaluated even if the underlying call took less time to return. Any delays in evaluating future will result in holding of permission in the underlying Semaphore.
      Type Parameters:
      T - the type of the returned Future result
      Parameters:
      bulkhead - the bulkhead
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateCheckedRunnable

      static io.vavr.CheckedRunnable decorateCheckedRunnable​(Bulkhead bulkhead, io.vavr.CheckedRunnable runnable)
      Returns a runnable which is decorated by a bulkhead.
      Parameters:
      bulkhead - the bulkhead
      runnable - the original runnable
      Returns:
      a runnable which is decorated by a Bulkhead.

    • decorateCallable

      static <T> java.util.concurrent.Callable<T> decorateCallable​(Bulkhead bulkhead, java.util.concurrent.Callable<T> callable)
      Returns a callable which is decorated by a bulkhead.
      Type Parameters:
      T - the result type of callable
      Parameters:
      bulkhead - the bulkhead
      callable - the original Callable
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateSupplier

      static <T> java.util.function.Supplier<T> decorateSupplier​(Bulkhead bulkhead, java.util.function.Supplier<T> supplier)
      Returns a supplier which is decorated by a bulkhead.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      bulkhead - the bulkhead
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateTrySupplier

      static <T> java.util.function.Supplier<io.vavr.control.Try<T>> decorateTrySupplier​(Bulkhead bulkhead, java.util.function.Supplier<io.vavr.control.Try<T>> supplier)
      Returns a supplier which is decorated by a bulkhead.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      bulkhead - the bulkhead
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateEitherSupplier

      static <T> java.util.function.Supplier<io.vavr.control.Either<java.lang.Exception,​T>> decorateEitherSupplier​(Bulkhead bulkhead, java.util.function.Supplier<io.vavr.control.Either<? extends java.lang.Exception,​T>> supplier)
      Returns a supplier which is decorated by a bulkhead.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      bulkhead - the bulkhead
      supplier - the original supplier
      Returns:
      a supplier which is decorated by a Bulkhead.

    • decorateConsumer

      static <T> java.util.function.Consumer<T> decorateConsumer​(Bulkhead bulkhead, java.util.function.Consumer<T> consumer)
      Returns a consumer which is decorated by a bulkhead.
      Type Parameters:
      T - the type of the input to the consumer
      Parameters:
      bulkhead - the bulkhead
      consumer - the original consumer
      Returns:
      a consumer which is decorated by a Bulkhead.

    • decorateCheckedConsumer

      static <T> io.vavr.CheckedConsumer<T> decorateCheckedConsumer​(Bulkhead bulkhead, io.vavr.CheckedConsumer<T> consumer)
      Returns a consumer which is decorated by a bulkhead.
      Type Parameters:
      T - the type of the input to the consumer
      Parameters:
      bulkhead - the bulkhead
      consumer - the original consumer
      Returns:
      a consumer which is decorated by a Bulkhead.

    • decorateRunnable

      static java.lang.Runnable decorateRunnable​(Bulkhead bulkhead, java.lang.Runnable runnable)
      Returns a runnable which is decorated by a bulkhead.
      Parameters:
      bulkhead - the bulkhead
      runnable - the original runnable
      Returns:
      a runnable which is decorated by a bulkhead.

    • decorateFunction

      static <T,​ R> java.util.function.Function<T,​R> decorateFunction​(Bulkhead bulkhead, java.util.function.Function<T,​R> function)
      Returns a function which is decorated by a bulkhead.
      Type Parameters:
      T - the type of the input to the function
      R - the type of the result of the function
      Parameters:
      bulkhead - the bulkhead
      function - the original function
      Returns:
      a function which is decorated by a bulkhead.

    • decorateCheckedFunction

      static <T,​ R> io.vavr.CheckedFunction1<T,​R> decorateCheckedFunction​(Bulkhead bulkhead, io.vavr.CheckedFunction1<T,​R> function)
      Returns a function which is decorated by a bulkhead.
      Type Parameters:
      T - the type of the input to the function
      R - the type of the result of the function
      Parameters:
      bulkhead - the bulkhead
      function - the original function
      Returns:
      a function which is decorated by a bulkhead.

    • ofDefaults

      static Bulkhead ofDefaults​(java.lang.String name)
      Create a Bulkhead with a default configuration.
      Parameters:
      name - the name of the bulkhead
      Returns:
      a Bulkhead instance

    • of

      static Bulkhead of​(java.lang.String name, BulkheadConfig config)
      Creates a bulkhead with a custom configuration
      Parameters:
      name - the name of the bulkhead
      config - a custom BulkheadConfig configuration
      Returns:
      a Bulkhead instance

    • of

      static Bulkhead of​(java.lang.String name, BulkheadConfig config, io.vavr.collection.Map<java.lang.String,​java.lang.String> tags)
      Creates a bulkhead with a custom configuration
      Parameters:
      name - the name of the bulkhead
      config - a custom BulkheadConfig configuration
      tags - tags added to the Bulkhead
      Returns:
      a Bulkhead instance

    • of

      static Bulkhead of​(java.lang.String name, java.util.function.Supplier<BulkheadConfig> bulkheadConfigSupplier)
      Creates a bulkhead with a custom configuration
      Parameters:
      name - the name of the bulkhead
      bulkheadConfigSupplier - custom configuration supplier
      Returns:
      a Bulkhead instance

    • of

      static Bulkhead of​(java.lang.String name, java.util.function.Supplier<BulkheadConfig> bulkheadConfigSupplier, io.vavr.collection.Map<java.lang.String,​java.lang.String> tags)
      Creates a bulkhead with a custom configuration
      Parameters:
      name - the name of the bulkhead
      bulkheadConfigSupplier - custom configuration supplier
      tags - tags added to the Bulkhead
      Returns:
      a Bulkhead instance

    • changeConfig

      void changeConfig​(BulkheadConfig newConfig)
      Dynamic bulkhead configuration change. NOTE! New `maxWaitTime` duration won't affect threads that are currently waiting for permission.
      Parameters:
      newConfig - new BulkheadConfig

    • tryAcquirePermission

      boolean tryAcquirePermission()
      Acquires a permission to execute a call, only if one is available at the time of invocation. If the current thread is interrupted while waiting for a permit then it won't throw InterruptedException, but its interrupt status will be set.
      Returns:
      true if a permission was acquired and false otherwise

    • acquirePermission

      void acquirePermission()
      Acquires a permission to execute a call, only if one is available at the time of invocation If the current thread is interrupted while waiting for a permit then it won't throw InterruptedException, but its interrupt status will be set.
      Throws:
      BulkheadFullException - when the Bulkhead is full and no further calls are permitted.
      io.github.resilience4j.core.exception.AcquirePermissionCancelledException - if thread was interrupted during permission wait

    • releasePermission

      void releasePermission()
      Releases a permission and increases the number of available permits by one.

      Should only be used when a permission was acquired but not used. Otherwise use onComplete() to signal a completed call and release a permission.

    • onComplete

      void onComplete()
      Records a completed call and releases a permission.

    • getName

      java.lang.String getName()
      Returns the name of this bulkhead.
      Returns:
      the name of this bulkhead

    • getBulkheadConfig

      BulkheadConfig getBulkheadConfig()
      Returns the BulkheadConfig of this Bulkhead.
      Returns:
      bulkhead config

    • getMetrics

      Bulkhead.Metrics getMetrics()
      Get the Metrics of this Bulkhead.
      Returns:
      the Metrics of this Bulkhead

    • getTags

      io.vavr.collection.Map<java.lang.String,​java.lang.String> getTags()
      Returns an unmodifiable map with tags assigned to this Bulkhead.
      Returns:
      the tags assigned to this Retry in an unmodifiable map

    • getEventPublisher

      Bulkhead.EventPublisher getEventPublisher()
      Returns an EventPublisher which subscribes to the reactive stream of BulkheadEvent and can be used to register event consumers.
      Returns:
      an EventPublisher

    • executeSupplier

      default <T> T executeSupplier​(java.util.function.Supplier<T> supplier)
      Decorates and executes the decorated Supplier.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original Supplier
      Returns:
      the result of the decorated Supplier.

    • executeTrySupplier

      default <T> io.vavr.control.Try<T> executeTrySupplier​(java.util.function.Supplier<io.vavr.control.Try<T>> supplier)
      Decorates and executes the decorated Supplier.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original Supplier
      Returns:
      the result of the decorated Supplier.

    • executeEitherSupplier

      default <T> io.vavr.control.Either<java.lang.Exception,​T> executeEitherSupplier​(java.util.function.Supplier<io.vavr.control.Either<? extends java.lang.Exception,​T>> supplier)
      Decorates and executes the decorated Supplier.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original Supplier
      Returns:
      the result of the decorated Supplier.

    • executeCallable

      default <T> T executeCallable​(java.util.concurrent.Callable<T> callable) throws java.lang.Exception
      Decorates and executes the decorated Callable.
      Type Parameters:
      T - the result type of callable
      Parameters:
      callable - the original Callable
      Returns:
      the result of the decorated Callable.
      Throws:
      java.lang.Exception - if unable to compute a result

    • executeRunnable

      default void executeRunnable​(java.lang.Runnable runnable)
      Decorates and executes the decorated Runnable.
      Parameters:
      runnable - the original Runnable

    • executeCheckedSupplier

      default <T> T executeCheckedSupplier​(io.vavr.CheckedFunction0<T> checkedSupplier) throws java.lang.Throwable
      Decorates and executes the decorated Supplier.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      checkedSupplier - the original Supplier
      Returns:
      the result of the decorated Supplier.
      Throws:
      java.lang.Throwable - if something goes wrong applying this function to the given arguments

    • executeCompletionStage

      default <T> java.util.concurrent.CompletionStage<T> executeCompletionStage​(java.util.function.Supplier<java.util.concurrent.CompletionStage<T>> supplier)
      Decorates and executes the decorated CompletionStage.
      Type Parameters:
      T - the type of results supplied by this supplier
      Parameters:
      supplier - the original CompletionStage
      Returns:
      the decorated CompletionStage.