[php-src] PR #21778: Fix GH-8739: opcache_reset()/invalidate() races via epoch-based reclamation
| From: | superdav42 | Date: | Thu, 16 Apr 2026 20:22:03 +0000 |
| Subject: | [php-src] PR #21778: Fix GH-8739: opcache_reset()/invalidate() races via epoch-based reclamation | ||
| Groups: | php.git-pulls | ||
| Request: | Send a blank email to git-pulls+get-35746@lists.php.net to get a copy of this message | ||
Pull Request: https://github.com/php/php-src/pull/21778
Author: superdav42
## Summary
Fixes the long-standing race in
opcache_reset()/opcache_invalidate() that
causes zend_mm_heap corrupted crashes under concurrent load in both ZTS (FrankenPHP,
parallel) and FPM configurations.
The writer destructively mutates ZCSG(hash) (memset) and the interned strings buffer
while readers may still hold pointers into that memory. The fix uses **epoch-based reclamation
(EBR)** — a lock-free pattern used by RCU in the Linux kernel and by Crossbeam in Rust — to
defer the destructive cleanup until all pre-reset readers have completed their requests.
## Why EBR (and not PR #14803's locking)
@dstogov rejected the prior attempt (#14803) because it took zend_shared_alloc_lock()
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 patch satisfies that constraint: **readers remain lock-free**. The per-request cost is two
atomic stores to cache-line-padded slots (no false sharing). Writers wait for readers to drain
instead of the other way around.
## Design
**Readers** (accel_activate, accel_post_deactivate):
- On request start: atomically publish ZCSG(current_epoch) to this thread's slot.
- On request end: atomically store ACCEL_EPOCH_INACTIVE to this thread's slot.
**Writers** (the deferred-restart path in accel_activate when
accel_is_inactive() is false):
- Record drain_epoch = current_epoch, increment current_epoch (new readers
publish a higher epoch).
- Set accelerator_enabled = false, reset_deferred = true.
- Do **not** call zend_accel_hash_clean() or
accel_interned_strings_restore_state() yet.
**Drain completion** (called from both accel_activate and
accel_post_deactivate):
- If min(slot[*].epoch) > drain_epoch and no overflow readers are active, take the
SHM lock and run the deferred cleanup.
## Safety under slot exhaustion
The per-slot pool is 256 slots × 64 cache-padded bytes = 16 KiB of SHM. Installations with more
than 256 concurrent threads/processes (large FPM pools) hit the overflow path: the aggregate
ZCSG(epoch_overflow_active) counter is incremented instead, and deferred reclamation is
held back until it reaches zero. This preserves correctness — overflow readers never disappear
silently.
## Test results
All tests pass with the change applied (--enable-debug --enable-zts --enable-opcache):
| Suite | Result |
|---|---|
| ext/opcache/tests | 876/876 pass |
| Zend/tests (with opcache loaded) | 4963/4963 pass |
| Full make test (28 extensions built) | 14643 pass, 1 pre-existing environmental
failure (verified fails without opcache too) |
Concurrent dev-server test: ~250 parallel requests with mixed opcache_reset() calls —
server remained responsive, no crashes, no heap corruption.
## Regression tests added
- ext/opcache/tests/gh8739_reset_epoch_safety.phpt — cached class remains accessible
after reset
- ext/opcache/tests/gh8739_reset_multiple.phpt — multiple resets don't crash
- ext/opcache/tests/gh8739_invalidate_epoch_safety.phpt — invalidate doesn't
crash while holding cached pointer
## Fixes
- Fixes GH-8739 (original 2022 report — string corruption with php-fpm 8.1.6)
- Fixes GH-14471 (reproducer — opcache_reset() crash under high load in FPM)
- Fixes GH-18517 (FrankenPHP ZTS opcache_reset memory corruption)
- Addresses FrankenPHP issues dunglas/frankenphp#1737, #2170, #2265
## Test plan
- [ ] CI green on PHP-8.4 matrix
- [ ] Reviewer runs the reproducer from GH-14471 (class T {} new T; opcache_reset();
under ab -c 24 -n 200000) — should no longer crash
- [ ] Reviewer runs the FrankenPHP reproducer at https://github.com/AlliBalliBaba/zts-opcache-reset-reproducer