From: Joel Rosdahl <joel@rosdahl.net>
Date: Mon, 6 Jan 2025 09:28:44 +0000 (+0100)
Subject: docs: Clarify how LRU cleanup works
X-Git-Tag: v4.11~27
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7ac4905c8373fb59aaa7c73c6636cf58665c3409;p=thirdparty%2Fccache.git

docs: Clarify how LRU cleanup works

Closes #1543.
---

diff --git a/doc/MANUAL.adoc b/doc/MANUAL.adoc
index d6346e69..8168a91c 100644
--- a/doc/MANUAL.adoc
+++ b/doc/MANUAL.adoc
@@ -1388,9 +1388,15 @@ Cleanup can be triggered in two different ways: automatic and manual.
 After a new compilation result has been written to the local cache, ccache will
 trigger an automatic cleanup if <<config_max_size,*max_size*>> or
 <<config_max_files,*max_files*>> is exceeded. The cleanup removes cache entries
-in LRU (least recently used) order based on the modification time (mtime) of
-files in the cache. For this reason, ccache updates mtime of the cache files
-read on a cache hit to mark them as recently used.
+in approximate LRU (least recently used) order based on the modification time
+(mtime) of files in the cache. For this reason, ccache updates mtime of the
+cache files read on a cache hit to mark them as recently used.
+
+For performance reasons only entries in a subset of the cache are considered
+when automatic cleanup is triggered. This means that there is no guarantee that
+the oldest entries of the whole cache are evicted on each individual cleanup,
+but over time the cache as a whole will be have "approximate LRU eviction"
+behavior.
 
 
 === Manual cleanup
@@ -1400,6 +1406,10 @@ recalculate the cache size information and also make sure that the cache size
 does not exceed <<config_max_size,*max_size*>> and
 <<config_max_files,*max_files*>>.
 
+Note that there is no guarantee that only the oldest entries are evicted, as
+discussed in _<<Automatic cleanup>>_ above. To evict based on age you can use
+`ccache --evict-older-than AGE`.
+
 
 == Cache compression