Overview of CasContainerStrategy::CollectGarbage implementation

1 files changed, 20 insertions, 0 deletions

diff --git a/zenstore/compactcas.cpp b/zenstore/compactcas.cpp
index 3d7eb695b..d5987c11e 100644
--- a/zenstore/compactcas.cpp
+++ b/zenstore/compactcas.cpp
@@ -254,6 +254,26 @@ CasContainerStrategy::CollectGarbage(GcContext& GcCtx)
 {
 	namespace fs = std::filesystem;
 
+	// Garbage collection will first remove any chunks that are flushed from the index.
+	// It then tries to compact the existing small object file, it does this by
+	// collecting all chunks that should be kept and sort them in position order.
+	// It then steps from chunk to chunk and checks if there is space to move the last
+	// chunk before the current chunk. It repeats this until it can't fit the last chunk
+	// or the last chunk is the current chunk.
+	// After this it check to see if there is space to move the current chunk closer to
+	// the preceeding chunk (or beginning of file if there is no preceeding chunk).
+	// It updates the new write position for any new chunks and rewrites the cas log
+	// to match the new content of the store.
+	//
+	// It currently grabs a full lock during the GC operation but the compacting is
+	// done gradually and can be stopped after each chunk if the GC operation needs to
+	// be time limited. This will leave holes in the small object file that will not
+	// be reclaimed unless a GC operation is executed again, but the state of the
+	// cas store is intact.
+	//
+	// It is also possible to more fine-grained locking of GC operation when moving
+	// blocks but that requires more work and additional checking if new blocks are
+	// added betwen each move of a block.
 	ZEN_INFO("collecting garbage from '{}'", m_Config.RootDirectory / m_ContainerBaseName);
 
 	const uint64_t TotalChunkCount = m_LocationMap.size();