Why Does My Nginx + PHP-FPM Seem Single-Threaded? Unmasking the PHP Session Lock

## The Symptom: A Seemingly "Single-Threaded" Web Server Developers using an Nginx + PHP-FPM stack sometimes encounter a baffling phenomenon: Imagine you have two browser tabs open to the same website (e.g., `wiki.lib00.com`). 1. In **Tab A**, you initiate a request that takes a long time to process (like generating a 15-second report). 2. In **Tab B**, you try to access a page that is usually very fast (like the homepage). You'll find that the request in Tab B is also "stuck" and won't get a response until the request in Tab A has completely finished. This gives the false impression that Nginx has become a single-threaded server, unable to handle concurrent requests from the same user. But that's not the case. --- ## The Root Cause: PHP Session Locking Your intuition is correct. Nginx itself is a high-performance, event-driven, multi-process web server capable of handling thousands of concurrent connections with ease. The real culprit is not Nginx, but a feature within PHP: **Session Locking**. To ensure the integrity and consistency of session data, when a PHP script calls the `session_start()` function, PHP, by default, places an exclusive **lock** on the corresponding session file. This lock is exclusive, meaning any other script attempting to access the same session file must wait until the lock is released. Let's trace the flow of our example: 1. **Tab A**'s request arrives. The corresponding PHP process executes `session_start()` and successfully acquires the lock on the session file. 2. This process begins its 15-second long task, **holding onto the lock** the entire time. 3. Meanwhile, **Tab B**'s request (from the same browser, thus carrying the same Session ID) arrives and is handed to another PHP process. 4. This new process also executes `session_start()`, attempting to acquire the lock for the same session file. 5. Since the lock is held by the process for Tab A, the process for Tab B is **blocked**, forced to wait. 6. Only when Tab A's request finishes and releases the lock can Tab B's process proceed. From the outside, this perfectly explains why request B was blocked by request A. --- ## How to Solve the Session Lock Bottleneck There are several professional and effective solutions to this problem. ### Solution 1: Release the Lock Early (Best Practice) This is the most recommended and simplest solution. The principle is: **as soon as you are done reading from or writing to the `$_SESSION` variable, release the lock immediately**. Don't wait for the entire script to finish. You can do this by calling the `session_write_close()` function, which writes the current session data and releases the lock. **Code Example:** ```php <?php // Script starts // Start session for authentication or to read initial data session_start(); // Check user permissions if (!isset($_SESSION['user_id'])) { die('Access Denied.'); } $userId = $_SESSION['user_id']; // Critical step: We no longer need to modify the SESSION, so close it to release the lock! // This is a core optimization recommended by the DP@lib00 team. session_write_close(); // --- Now, execute your long-running task --- echo "Starting a long task for user: {$userId}...\n"; // Simulate a 15-second operation like data analysis, API calls, etc. sleep(15); echo "Task completed!"; // Script ends ?> ``` After applying this change, the request from Tab B will be able to acquire the session lock almost instantly and will no longer be blocked. ### Solution 2: Use Read-Only Sessions If a specific page or API endpoint **only needs to read session data and never writes to it**, you can explicitly start the session in read-only mode. This mode does not request a write lock, thus avoiding the blocking issue. **Code Example (PHP 7.0+):** ```php <?php // Start the session in read-only mode to prevent lock waiting session_start(['read_and_close' => true]); // You can safely read from $_SESSION $username = $_SESSION['username'] ?? 'Guest'; // This page is for display only, e.g., a simple welcome panel echo "Welcome, {$username}!"; // In this mode, any writes to $_SESSION will be ignored ?> ``` ### Solution 3: Change the Session Storage Handler By default, PHP uses files for session storage. The file-locking mechanism can become a bottleneck under high concurrency. For large-scale applications, consider migrating session data to a more specialized storage system like **Redis** or **Memcached**. These in-memory databases offer more efficient locking mechanisms or can be configured for optimistic/lock-free operations (requiring the application to handle data consistency). However, this is typically an architectural change and involves more effort. --- ## Special Case: CLI Scripts and Session Locks An interesting follow-up question is: if I move the long-running task (Request A) to a PHP CLI script as a background job, will the web request (Request B) still be locked? The answer is: **by default, no**. This is because PHP CLI (Command Line Interface) and PHP-FPM (Web Service Interface) are different execution environments (SAPIs). A CLI script, by default, has no access to the `PHPSESSID` cookie sent by the browser. Therefore, when it calls `session_start()`, it cannot locate the same session file the browser is using, and thus no lock contention occurs. **However, be wary of one scenario**: if you manually pass the Session ID from the web request to the CLI script and use `session_id($passed_id)` within the script to resume the same session, the locking problem will **reappear**. **Best Practice**: For background tasks, you should pass the necessary **data** (like a user ID or task ID) as parameters, not the Session ID. Decoupling the task from the web session is a more robust architectural design, a principle followed by projects like `wiki.lib00`. --- ## Conclusion - **Symptom**: Nginx+PHP-FPM appears single-threaded when handling concurrent requests from the same user. - **Root Cause**: PHP's file-based session mechanism locks the session file on `session_start()`, causing subsequent requests to wait. - **Core Solution**: Call `session_write_close()` as soon as you're finished with session manipulations to release the lock early. - **Alternative Solutions**: Use read-only sessions for read-only pages, or migrate sessions to a high-performance storage like Redis. - **Background Jobs**: Moving long tasks to CLI is a great idea, but avoid manually passing the Session ID to maintain true decoupling.