Modx 2.6+ File‑Based Cache Locking: Unresolved Latency Under Concurrent Requests

Answer

Modx detects orphaned lock files only by comparing their age to the lockTTL setting; if a lock is older than lockTTL it is treated as stale and may be ignored, allowing a new writer to proceed. There is no automatic cleanup or recovery mechanism beyond this stale‑lock check.

The file‑based cache adapter exposes two tunable options: lockWait (microseconds to sleep between flock attempts) and lockTTL (seconds after which a lock is considered stale). Both can be set at runtime via $modx->cacheManager->setOptions() or through system settings (cache_lock_wait, cache_lock_ttl). Changing them does not require clearing the cache.

When multiple requests try to write the same cache entry, each obtains an exclusive flock on the companion .lock file in the order the lock succeeds. Requests that cannot acquire the lock sleep lockWait microseconds and retry, so latency grows roughly linearly with the number of waiting writers. No built‑in queueing, priority, or undocumented option exists to change this serialization order.

Likely explanation vs confirmed facts

Confirmed facts (from the code and documentation):

• Modx uses PHP flock() on a .lock file; lock acquisition is blocking unless a custom retry loop with lockWait is used.
• LockTTL is checked only when a lock attempt finds an existing lock file; if the file’s modification time is older than lockTTL seconds, the lock is treated as stale and may be ignored.
• There is no background process that removes .lock files; orphaned locks persist until a subsequent writer treats them as stale.
• lockWait and lockTTL are exposed as adapter options and can be changed without flushing the cache.

Likely explanation for observed latency under concurrent writes:

• Each writer holds the exclusive lock for the duration of the cache‑write operation (file put + metadata update). While one writer holds the lock, all others sleep lockWait microseconds per retry, adding wait time proportional to the number of contending requests.
• If lockTTL is set too low relative to the actual write time, a lock may be deemed stale while the original writer is still active, leading to overlapping writes and possible cache corruption.
• Conversely, a very high lockTTL prevents false stale‑lock detection but can cause orphaned locks to block new writers for longer periods if a request terminates unexpectedly.

Steps to mitigate latency in this case

1. Measure the typical cache‑write duration (e.g., by timing a single request that writes the same key).
2. Set lockTTL to a value safely above that duration (for example, write time × 2) to avoid treating valid locks as stale.
3. Reduce lockWait to a small value (e.g., 10 000 µs) if CPU usage is acceptable, or increase it to reduce busy‑waiting when contention is high.
4. If latency remains unacceptable, consider lowering the frequency of writes (e.g., cache warming, using a longer cache lifetime) or switching to a non‑file backend such as APCu, Memcached, or Redis.

To confirm whether adjusting lockTTL or lockWait will resolve the latency, please provide the average time a single cache write takes on your system (or the observed lock‑file age when requests appear to stall). This detail determines whether the current lockTTL is too low or too high and thus changes the recommendation.