Bulkhead class

Caps the number of concurrently in-flight Result-returning operations, optionally queueing the overflow.

The bulkhead pattern isolates a slow or failing downstream so it cannot exhaust client-side resources (threads, sockets, memory). Callers above the configured concurrency wait in a FIFO queue; once the queue is also full, additional callers receive Error(Failure.bulkheadRejected()) instead of being kept waiting.

final bulkhead = Bulkhead(maxConcurrent: 8, maxQueueSize: 16);

final result = await bulkhead.execute(() => api.fetchUser(id));
// If the bulkhead is full, `result` is an Error with
// FailureKind.bulkheadRejected — the underlying call was not made.

Composes naturally with CircuitBreaker, RetryHelper, and ResultCache: wrap the bulkhead around the call to bound resource use, then layer retries / caching outside it as needed.