doc/architecture-gc.rst: describe how GC operates

The current code is really simple, so a whole summary fits easily.

diff --git a/doc/architecture-gc.rst b/doc/architecture-gc.rst
index 257a4801622fe0114b3b00f85f119409a1806e06..b57c857c39bb5a928ebf8e1a2e4adc4412e1dd40 100644 (file)
--- a/doc/architecture-gc.rst
+++ b/doc/architecture-gc.rst
@@ -1,3 +1,12 @@
 *****************
 ``kres-cache-gc``
-*****************
\ No newline at end of file
+*****************
+
+The garbage collector is a simple component which keeps the shared cache from overfilling.
+Every second it estimates cache usage and if over 80%, records get deleted in order to free 10%.  (Parameters can be configured.)
+
+The freeing happens in a few passes.  First all items are classified by their estimated usefulness, in a simple way based on remaining TTL, type, etc.
+From this histogram it's computed which "level of usefulness" will become the threshold, so that roughly the planned total size gets freed.
+Then all items are passed to collect the set of keys to delete, and finally the deletion is performed.
+As longer transactions can cause issues in LMDB, all passes are split into short batches.
+