Document Oak
Memoirs in Garbage Collection (WIP):
Describe usage of MemoryNodeBuilder in Compactor to handle many direct child nodes and track the stableId
@@ -101,8 +101,8 @@ This logic is captured in the respective implementations of the [reclaim predica
> *Note:* Oak 1.8.0 had a [bug](https://issues.apache.org/jira/browse/OAK-7132) in the implementation of the reclamation mechanism described. The bug was fixed with Oak 1.8.1, which is the version of Oak this section is referring to.
-* TODO: describe usage of MemoryNodeBuilder and modCount in Compactor
-* TODO: describe usage and implementation of stableIds in Compactor
+### The Compactor strikes back
+Oak 1.6 removed the [`Compactor` class](https://github.com/apache/jackrabbit-oak/blob/1.4/oak-segment/src/main/java/org/apache/jackrabbit/oak/plugins/segment/Compactor.java#L54) in favour of directly rewriting node states with the [`SegmentWriter`](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.6.0/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java#L85) solely relying on deduplication caches for deduplicating records. To implement sequential checkpoint rebasing and tail compaction Oak 1.8 reintroduced a new implementation of a [`Compactor` class](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L56). This implementation has to deal with two additional requirements compared to the previous implementation: tracking and assigning stable ids and being able to cope with a large number of direct child nodes of a node. This is done by tracking changes with a [`MemoryNodeBuilder`](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L163) instead of using a `NodeBuilder` acquired through calling `NodeState.builder`. The new [`SegmentWriter.write`](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/SegmentWriter.java#L130) method with an extra argument for the stable is then used to [write](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L175) compacted node states including their stable id. In addition the number of updates to the `MemoryNodeBuilder` are [tracked](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L154-L160) and an [intermediate node is written](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L156) to avoid keeping to many updates in memory once an [update limit](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L62) is exceeded. Further updates are tracked in a fresh `MemoryNodeBuilder` instance that uses this [intermediate node as its base](https://github.com/apache/jackrabbit-oak/blob/jackrabbit-oak-1.8.1/oak-segment-tar/src/main/java/org/apache/jackrabbit/oak/segment/Compactor.java#L157).
Oak 1.10
