Skill: Mutex coordination

Read the bundled conventions before applying this skill.

Decisions that affect behavior

• Identify which processes/hosts must coordinate and which backend they actually share. FileMutex, database advisory locks, and external implementations have different scope and lifetime. A local filesystem lock is not automatically a distributed lock, and a shared cache entry is not an equivalent mutex.
• Use a stable lock name representing the protected resource and preserve existing application/environment namespace conventions. Different spellings or backends do not protect the same critical section.
• acquire() returns a boolean; timeout zero means immediate failure when unavailable. Execute protected work only after success, and handle timeout according to the application’s existing retry/failure contract. Yii tracks acquired names locally; acquiring the same name again through one Mutex instance is not reentrant.
• Release an acquired lock in a finally path and check unexpected release failure where it affects correctness. autoRelease is a process-shutdown safeguard, not a substitute for promptly releasing a lock in a long-running worker.
• isAcquired() reports this object’s local acquisition state, not whether another process holds the lock. Do not use it as a global availability check before entering protected work; acquisition itself decides ownership.
• A mutex does not commit/rollback database work or guarantee an external side effect occurs exactly once. Preserve database constraints, transactions and idempotency requirements. Inspect driver connection lifetime/reconnection when relying on a database-backed advisory lock.

Observable acceptance

With isolated lock names and the intended backend, verify acquisition, failed or bounded competing acquisition, release, and reacquisition. Test exception cleanup. Use independent processes/connections when validating actual contention; calling one in-memory double twice only verifies local bookkeeping. Never acquire a live production lock merely as a generic test or claim multi-host safety from one host.

Evidence routes

Read framework/mutex/{Mutex,FileMutex,DbMutex,MysqlMutex,PgsqlMutex,OracleMutex}.php and the selected implementation. Tests: tests/framework/mutex/MutexTest.php, MutexTestTrait.php, FileMutexTest.php, and driver-specific tests in that directory. Use the selected class’s PHPDoc for backend-specific scope and timeout behavior.

Install and activate this skill

Select yii2-mutex in the installation and client verification guide. Install the complete bundle, including referenced resources. The canonical SKILL.md is also available for direct reading.

Continue with the related framework guide.