acc-create-bulkhead

name: acc-create-bulkhead description: Generates Bulkhead pattern for PHP 8.5. Creates resource isolation with semaphore-based concurrency limiting and thread pool isolation. Includes unit tests.

Bulkhead Pattern Generator

Creates Bulkhead pattern infrastructure for resource isolation and fault containment.

When to Use

Component Characteristics

BulkheadInterface

• Common interface for all isolation strategies
• Acquire and release semantics
• Capacity monitoring

Strategies

• Semaphore Bulkhead: Limits concurrent executions
• Thread Pool Bulkhead: Isolates execution with dedicated pool
• Queue-based Bulkhead: Limits with waiting queue

BulkheadFullException

• Thrown when bulkhead capacity exhausted
• Contains bulkhead name and capacity info

Generation Process

Step 1: Generate Core Components

Path: src/Infrastructure/Resilience/Bulkhead/

1. BulkheadInterface.php — Common interface
2. BulkheadConfig.php — Configuration value object
3. BulkheadFullException.php — Exception with capacity info

Step 2: Generate Bulkhead Implementation

Choose based on use case:

1. SemaphoreBulkhead.php — Local semaphore-based limiting
2. DistributedSemaphoreBulkhead.php — Redis-based for multi-instance

Step 3: Generate Registry (Optional)

1. BulkheadRegistry.php — Manages multiple bulkheads

Step 4: Generate Tests

1. SemaphoreBulkheadTest.php — Bulkhead behavior tests
2. BulkheadConfigTest.php — Configuration tests

File Placement

Naming Conventions

Quick Template Reference

BulkheadInterface

interface BulkheadInterface
{
    public function execute(callable $operation): mixed;
    public function tryAcquire(): bool;
    public function release(): void;
    public function getAvailablePermits(): int;
    public function getActiveCount(): int;
    public function getName(): string;
}

BulkheadConfig

final readonly class BulkheadConfig
{
    public function __construct(
        public int $maxConcurrentCalls = 10,
        public int $maxWaitDuration = 0,
        public bool $fairness = true
    ) {}

    public static function default(): self;
    public static function forCpuBound(int $cpuCores): self;
    public static function forIoBound(int $cpuCores): self;
    public static function forExternalService(int $maxConnections): self;
}

Usage Example

// Create limiter
$bulkhead = new SemaphoreBulkhead(
    name: 'payment-gateway',
    config: BulkheadConfig::forExternalService(maxConnections: 20),
    logger: $logger
);

// Execute with isolation
try {
    $result = $bulkhead->execute(fn() => $client->charge($request));
} catch (BulkheadFullException $e) {
    return Result::serviceOverloaded();
}

Use Case Selection

Anti-patterns to Avoid

References

For complete PHP templates and examples, see:

• references/templates.md — BulkheadInterface, Config, SemaphoreBulkhead, DistributedSemaphoreBulkhead, Registry
• references/examples.md — PaymentGatewayAdapter, ConnectionPool, OrderService examples and tests