Bulkhead#

Resilience4j's Bulkhead limits the number of concurrent calls to a service, shedding load when the concurrency ceiling is reached. It is implemented as a semaphore-backed abstraction 1 with a single production implementation: SemaphoreBulkhead.

Key configuration parameters (set via BulkheadConfig):

• maxConcurrentCalls — the semaphore permit count 2
• maxWaitDuration — how long to wait for a permit before throwing BulkheadFullException; 0 = fail-fast 3
• fairCallHandlingEnabled — whether the underlying semaphore uses fair ordering 4

Events published: CallPermitted, CallRejected, CallFinished 5

Synchronous API#

The core synchronous lifecycle is:

1. Acquire — tryAcquirePermission() (returns bool) or acquirePermission() (throws on rejection) 6
2. Execute your call
3. Release — always call onComplete() when done, or releasePermission() if the permit was acquired but not used 7

Decorator helpers covering Supplier, Callable, Runnable, Function, Consumer, CompletionStage, and Future types are static methods on the Bulkhead interface. The BulkheadFuture wrapper ensures onComplete() is called exactly once when Future.get() returns 8.

⚠️ decorateCompletionStage calls tryAcquirePermission() (fail-fast, non-queued) and wraps the result in a new CompletableFuture. It does not use the async permit queue described below 9.

Non-Blocking Async Permit Acquisition (acquirePermissionAsync)#

Added in PR #2506 to fix a critical issue: the previous Reactor operators blocked the calling thread (Netty event loop) when maxWaitDuration > 0, degrading reactive throughput.

Bulkhead.acquirePermissionAsync() returns a CompletableFuture<Void> that never parks the calling thread 10. Three completion paths in SemaphoreBulkhead:

PendingPermission is a CompletableFuture<Void> subclass with an atomic state machine (PENDING → GRANTED | EXPIRED | CANCELLED). Grant, expiry (via a shared ScheduledExecutorService), and cancellation compete on a single CAS — only the winner completes the future, preventing permit leaks 14.

Cancellation contract: Calling cancel() on the returned future removes the request from the queue without publishing a CallRejected event (the caller withdrew the request). If cancel() returns false, a permit was already granted and must still be released 15.

Drain loop: grantPendingPermissions() uses a work-in-progress counter to avoid recursion when synchronous continuations immediately release a permit 16. Event consumer failures do not interrupt the drain — they are rethrown once the drain is complete.

Backward compatibility: The interface defines a blocking-bridge default implementation of acquirePermissionAsync() for custom Bulkhead subclasses. SemaphoreBulkhead overrides it with the fully non-blocking version 17.

Kotlin Integration#

The resilience4j-kotlin module provides coroutine-aware extensions in two files.

Suspend Functions — Bulkhead.kt#

• Bulkhead.executeSuspendFunction(block) — acquires a permit, runs the suspend block, then calls onComplete(). On cancellation, calls releasePermission() instead of onComplete() 18.
• Bulkhead.decorateSuspendFunction(block) — returns a decorated suspend lambda 19.
• Internal acquirePermissionSuspend() 20: fast-path calls acquirePermission() directly when maxWaitDuration = 0; otherwise dispatches to Dispatchers.IO to avoid blocking the coroutine dispatcher.

⚠️ The Kotlin suspend extensions still use the synchronous acquirePermission() path (not acquirePermissionAsync()). Using a non-zero maxWaitDuration will block an IO thread. For reactive use cases, prefer acquirePermissionAsync() via the Reactor operators.

Flow Operator — FlowBulkhead.kt#

Flow<T>.bulkhead(bulkhead: Bulkhead): Flow<T>

Wraps an upstream Flow with bulkhead protection 21:

1. Acquires a permit via acquirePermissionSuspend() before collecting from upstream.
2. Attaches an onCompletion handler: calls releasePermission() on cancellation, onComplete() otherwise.

Cancellation Detection — Cancellation.kt#

isCancellation(coroutineContext, error) returns true when the coroutine's Job is cancelled or the error is a CancellationException 22. Both executeSuspendFunction and the Flow operator use this to decide whether to call releasePermission() (no work done) vs. onComplete() (work completed normally or with a non-cancellation error).

Key Source Files#