Semaphore Laravel Package

Getting Started

Minimal Setup

1. Installation:

   composer require zerkalica/semaphore
   

   Add the service provider to config/app.php:

   'providers' => [
       // ...
       Zerkalica\Semaphore\SemaphoreServiceProvider::class,
   ],
   

2. Basic Usage:

   use Zerkalica\Semaphore\Facades\Semaphore;
   
   // Acquire a semaphore (blocking)
   Semaphore::acquire('my_resource');
   
   // Release the semaphore
   Semaphore::release('my_resource');
   

3. First Use Case: Limit concurrent database imports to 3:

   Semaphore::acquire('import_lock', 3);
   // Critical section (e.g., import logic)
   Semaphore::release('import_lock');
   

Implementation Patterns

Workflow Integration

1. Resource Guarding:

   // In a controller/middleware
   Semaphore::acquire('api_rate_limit', 10);
   try {
       // Process request
   } finally {
       Semaphore::release('api_rate_limit');
   }
   

2. Non-Blocking Checks:

   if (Semaphore::tryAcquire('exclusive_task', 1)) {
       // Execute critical task
       Semaphore::release('exclusive_task');
   } else {
       // Fallback or queue
   }
   

3. Laravel Events:

   // In an event listener
   Semaphore::acquire('event_processor');
   // Process event
   Semaphore::release('event_processor');
   

Advanced Patterns

• Context Managers:

  Semaphore::acquire('resource');
  try {
      // Business logic
  } finally {
      Semaphore::release('resource');
  }
  

• Rate Limiting Middleware:

  public function handle($request, Closure $next) {
      Semaphore::acquire('api_limit', 100);
      $response = $next($request);
      Semaphore::release('api_limit');
      return $response;
  }
  

Gotchas and Tips

Pitfalls

1. Deadlocks:

   • Always release semaphores in finally blocks.
   • Avoid nested acquisitions (e.g., A → B → A).

2. Resource Leaks:

   • Unreleased semaphores block indefinitely. Use tryAcquire() for timeouts:

     if (!Semaphore::tryAcquire('resource', 1, 5)) { // 5-second timeout
         throw new \RuntimeException('Resource unavailable');
     }
     

3. Cross-Process Safety:

   • The package uses file-based semaphores (default: storage/framework/semaphores/).
   • Ensure proper file permissions (chmod -R 775 storage/framework/semaphores).

Debugging

• Check Lock Files:

  ls -la storage/framework/semaphores/
  

  Manually delete stale locks if needed (restart app afterward).

• Logging: Enable debug mode in config/semaphore.php:

  'debug' => env('SEMAPHORE_DEBUG', false),
  

Extension Points

1. Custom Storage: Override the default storage engine by binding a Zerkalica\Semaphore\Contracts\SemaphoreStorage implementation:

   $this->app->bind('semaphore.storage', function() {
       return new CustomRedisSemaphoreStorage();
   });
   

2. Event Hooks: Listen for semaphore events (e.g., semaphore.acquired, semaphore.released) via Laravel’s event system.

3. Configuration: Adjust timeouts in config/semaphore.php:

   'timeout' => 30, // Seconds
   'retry_interval' => 100, // Milliseconds