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

      All Methods Static Methods Instance Methods Abstract Methods Default Methods 
      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 Detail

      • 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.