[php-src] PR #21775: Fix opcache_reset()/opcache_invalidate() races using epoch-based reclamation
| From: | superdav42 | Date: | Thu, 16 Apr 2026 17:11:24 +0000 |
| Subject: | [php-src] PR #21775: Fix opcache_reset()/opcache_invalidate() races using epoch-based reclamation | ||
| Groups: | php.git-pulls | ||
| Request: | Send a blank email to git-pulls+get-35742@lists.php.net to get a copy of this message | ||
Pull Request: https://github.com/php/php-src/pull/21775
Author: superdav42
## Summary
opcache_reset() and opcache_invalidate() destroy shared memory
(memset on hash table, interned strings restore, SHM watermark reset) while concurrent
reader threads/processes still hold pointers into that memory. This causes **zend_mm_heap
corrupted** crashes under concurrent load in both **ZTS** (FrankenPHP, parallel) and **FPM**
configurations.
This has been open since 2022 and is increasingly critical as FrankenPHP adoption grows.
### Root cause
Three race conditions in ext/opcache/ZendAccelerator.c:
1. **Hash table lookup vs reset** — persistent_compile_file() finds a bucket in
ZCSG(hash), then opcache_reset() zeroes the hash table via
memset, leaving the bucket pointer dangling.
2. **Interned string lifetime** — accel_interned_strings_restore_state() resets the
interned strings buffer while threads still hold zend_string* pointers to it.
zend_string_release() then frees a pointer in the shared region, not the thread's
heap → zend_mm_heap corrupted.
3. **Script corruption flag** — persistent_script->corrupted is read without
synchronization while another thread sets it.
### Why the previous fix (PR #14803) was rejected
PR #14803 by @ndossche wrapped find+add sequences with zend_shared_alloc_lock().
**@dstogov rejected it** because it introduced global locking on every cache lookup:
> "Please think about a different solution. This one should make a big slowdown. opcache
> should be able to do lock-free cache lookups. Probably, the modification of
> ZCSG(hash) should be done more careful (to keep consistency for
> concurrent readers)"
**This PR satisfies that constraint: readers remain completely lock-free.**
### Solution: Epoch-Based Reclamation (EBR)
A well-proven pattern from lock-free data structure research (Fraser 2004, Hart et al. 2007), used
in the Linux kernel (RCU), FreeBSD, and Crossbeam (Rust).
**Reader protocol** (per-request, lock-free):
1. On request start: publish thread_epoch = global_epoch (one atomic store to a
cache-line-padded slot)
2. Execute request (reads shared OPcache data freely, no locks)
3. On request end: publish thread_epoch = INACTIVE (one atomic store)
**Writer protocol** (opcache_reset):
1. Record drain_epoch = current_epoch
2. Increment current_epoch (new requests enter new generation)
3. Disable caching, set reset_deferred = true
4. At the next request boundary, check: min(all active thread epochs) > drain_epoch?
- Yes → all old readers done, safe to run the actual cleanup
- No → check again at the next request end
The legacy immediate-reset path is retained as a fast path when accel_is_inactive()
confirms no readers are active.
### Per-request overhead
Two atomic stores per request (enter + leave), each to a dedicated 64-byte cache-line-padded slot.
No false sharing, no locks, no contention. The deferred reset scan (min_active_epoch)
is O(256) but only runs at request boundaries when a reset is pending.
### Files changed
| File | Changes |
|---|---|
| ext/opcache/ZendAccelerator.h | Epoch slot struct, 64-bit atomic macros
(MSVC/Clang/GCC), epoch fields in shared & per-thread globals |
| ext/opcache/ZendAccelerator.c | Epoch lifecycle functions, deferred reset in RINIT,
epoch leave in post_deactivate, init in SHM startup |
| ext/opcache/zend_accelerator_hash.c | Memory barrier after
zend_accel_hash_clean() memset |
| ext/opcache/tests/gh8739_*.phpt | Regression tests |
| NEWS | Entry for the fix |
### Testing
- Builds cleanly with --enable-zts (zero warnings on GCC)
- opcache_reset() + continued script access works without crash
- Multiple sequential opcache_reset() calls work without crash
- Concurrent stress testing needed (TSAN/ASAN recommended for full validation)
### References
- #8739 — original report (2022)
- #14471 — reproducer under high load FPM (2024)
- #18517 — FrankenPHP-specific ZTS report
- #14803 — rejected PR (global lock approach)
- https://github.com/dunglas/frankenphp/issues/1737
— WordPress multisite crashes every ~8h
- https://github.com/dunglas/frankenphp/issues/2265
— worker restart corrupts heap
- https://github.com/dunglas/frankenphp/issues/2170
— Symfony deploy crash
Fixes #8739
Fixes #14471
Fixes #18517