Interface Bulkhead

All Known Implementing Classes:
Bulkhead.SemaphoreBulkhead, Bulkhead.ThreadPoolBulkhead
public sealed interface Bulkhead permits Bulkhead.SemaphoreBulkhead, Bulkhead.ThreadPoolBulkhead
Bulkhead - Resource isolation for cache operations 舱壁 - 缓存操作的资源隔离

Provides thread pool isolation to prevent cascade failures by limiting concurrent operations and isolating different cache operations.

通过限制并发操作并隔离不同的缓存操作，提供线程池隔离以防止级联故障。

Features | 主要功能:

  • Semaphore-based bulkhead - 基于信号量的舱壁
  • Thread pool-based bulkhead - 基于线程池的舱壁
  • Configurable max concurrent calls - 可配置最大并发调用数
  • Configurable max wait duration - 可配置最大等待时间
  • Metrics collection - 指标收集

Usage Examples | 使用示例:

// Semaphore-based bulkhead - 基于信号量的舱壁
Bulkhead bulkhead = Bulkhead.semaphore("db-operations")
    .maxConcurrentCalls(10)
    .maxWaitDuration(Duration.ofMillis(500))
    .build();

String result = bulkhead.execute(() -> loadFromDb(key));

// Thread pool-based bulkhead - 基于线程池的舱壁
Bulkhead poolBulkhead = Bulkhead.threadPool("async-operations")
    .corePoolSize(5)
    .maxPoolSize(10)
    .queueCapacity(100)
    .build();

CompletableFuture<String> future = poolBulkhead.submitAsync(() -> loadAsync(key));

Performance | 性能特性:

  • Time complexity: O(1) for permit acquire - 时间复杂度: O(1) 获取许可
  • Space complexity: O(n) for queue - 空间复杂度: O(n) 队列

Security | 安全性:

  • Thread-safe: Yes - 线程安全: 是
  • Null-safe: Yes - 空值安全: 是
Since:
JDK 25, opencode-base-cache V1.0.0
Author:
Leon Soo www.LeonSoo.com
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Interface
    Description
    static class 
    Bulkhead.BulkheadFullException
    Exception thrown when bulkhead is full 舱壁已满时抛出的异常
    static final record 
    Bulkhead.Metrics
    Bulkhead metrics 舱壁指标
    static class 
    Bulkhead.SemaphoreBuilder
    Builder for semaphore-based bulkhead 信号量舱壁构建器
    static final class 
    Bulkhead.SemaphoreBulkhead
    Semaphore-based bulkhead implementation 基于信号量的舱壁实现
    static class 
    Bulkhead.ThreadPoolBuilder
    Builder for thread pool-based bulkhead 线程池舱壁构建器
    static final class 
    Bulkhead.ThreadPoolBulkhead
    Thread pool-based bulkhead implementation 基于线程池的舱壁实现

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    close()
    Close bulkhead and release resources 关闭舱壁并释放资源
    <T> T
    execute(Supplier<T> supplier)
    Execute operation with bulkhead protection 在舱壁保护下执行操作
    default <T> T
    execute(Supplier<T> supplier, Supplier<T> fallback)
    Execute operation with fallback 执行操作并带降级
    <T> CompletableFuture<T>
    executeAsync(Supplier<T> supplier)
    Execute operation asynchronously 异步执行操作
    Bulkhead.Metrics
    getMetrics()
    Get current metrics 获取当前指标
    String
    name()
    Get bulkhead name 获取舱壁名称
    void
    release()
    Release a permit back to the bulkhead 释放许可回到舱壁
    static Bulkhead.SemaphoreBuilder
    semaphore(String name)
    Create semaphore-based bulkhead builder 创建基于信号量的舱壁构建器
    static Bulkhead.ThreadPoolBuilder
    threadPool(String name)
    Create thread pool-based bulkhead builder 创建基于线程池的舱壁构建器
    boolean
    tryAcquire()
    Try to acquire a permit from the bulkhead 尝试从舱壁获取许可

  • Method Details

    • execute

      <T> T execute(Supplier<T> supplier)
      Execute operation with bulkhead protection 在舱壁保护下执行操作
      Type Parameters:
      T - result type | 结果类型
      Parameters:
      supplier - the operation | 操作
      Returns:
      result | 结果
      Throws:
      Bulkhead.BulkheadFullException - if bulkhead is full | 舱壁已满时抛出异常

    • execute

      default <T> T execute(Supplier<T> supplier, Supplier<T> fallback)
      Execute operation with fallback 执行操作并带降级
      Type Parameters:
      T - result type | 结果类型
      Parameters:
      supplier - the operation | 操作
      fallback - the fallback | 降级操作
      Returns:
      result | 结果

    • executeAsync

      <T> CompletableFuture<T> executeAsync(Supplier<T> supplier)
      Execute operation asynchronously 异步执行操作
      Type Parameters:
      T - result type | 结果类型
      Parameters:
      supplier - the operation | 操作
      Returns:
      future containing result | 包含结果的 Future

    • name

      String name()
      Get bulkhead name 获取舱壁名称
      Returns:
      name | 名称

    • getMetrics

      Bulkhead.Metrics getMetrics()
      Get current metrics 获取当前指标
      Returns:
      metrics | 指标

    • close

      void close()
      Close bulkhead and release resources 关闭舱壁并释放资源

    • tryAcquire

      boolean tryAcquire()
      Try to acquire a permit from the bulkhead 尝试从舱壁获取许可
      Returns:
      true if permit acquired | 获取许可返回 true

    • release

      void release()
      Release a permit back to the bulkhead 释放许可回到舱壁

    • semaphore

      static Bulkhead.SemaphoreBuilder semaphore(String name)
      Create semaphore-based bulkhead builder 创建基于信号量的舱壁构建器
      Parameters:
      name - bulkhead name | 舱壁名称
      Returns:
      builder | 构建器

    • threadPool

      static Bulkhead.ThreadPoolBuilder threadPool(String name)
      Create thread pool-based bulkhead builder 创建基于线程池的舱壁构建器
      Parameters:
      name - bulkhead name | 舱壁名称
      Returns:
      builder | 构建器