The cache API deals with stale cache items in a non-consistent way. I propose some changes that will make common usage of the API easier while allowing callers to make better use of stale (invalid/expired) data.
$cache->get() may return expired values. This may sometimes be useful, but callers need to check the expire time themselves. This is a somewhat unexpected behaviour (filed as a bug here:).
On the other hand, if an item has been invalided via $cache->invalidateTags(), it cannot be retrieved via $cache->get(), even if it has not yet been deleted from the backend.
The cache API uses very inconsistent wording when it comes to “removing” cache entries:
- $cache->flush() deletes all items – I propose a renaming to deleteAll() (for consistency with delete() and deleteMultiple()).
- $cache->expire() deletes entries that have expired – I propose a renaming to deleteExpired().
- $cache->invalidateTags() effectively deletes entries with the specified tags (they are not deleted right away, but they cannot be retrieved through get()). I suggest we stick to this but extend $cache->get() with the possibility to retrieve those values.
In addition to implementing these proposals, the attached patch adds the following:
- Two new functions, $cache->invalidate($cid) and $cache->invalidateMultiple($cid), that mark existing cache items as invalid. This is equivalent to modifying the items so they get an expire time in the past.
- $cache->get()/getMultiple() gets an options second argument, $cache->get($cid, $allowInvalid) and $cache->getMultiple($cids, $allowInvalid), that specifies whether expired or explicitly invalidated (via $cache->invalidate()/invalidateMultiple()/invalidateTags()) items should be returned. By default only valid items are returned.
- cache_invalidate() is renamed to cache_invalidate_tags() to match $cache->invalidateTags() and not be confused with $cache->invalidate().
- The structure of DatabaseBackend and MemoryBackend are brought more in sync. We should consider introducing a common abstract base class, BackendBase, that implements shared functionality.
- Terminology clean-up in tests and Doxygen comments.
PASSED: [[SimpleTest]]: [MySQL] 48,948 pass(es).
FAILED: [[SimpleTest]]: [MySQL] Unable to apply patch cache-invalid-15.patch. Unable to apply patch. See the log in the details link for more information.
PASSED: [[SimpleTest]]: [MySQL] 48,865 pass(es).
FAILED: [[SimpleTest]]: [MySQL] 48,201 pass(es), 16 fail(s), and 30 exception(s).
PASSED: [[SimpleTest]]: [MySQL] 46,330 pass(es).