maple_tree: Thoughts updated for coalescing/rebuilding

Signed-off-by: Liam R. Howlett <Liam.Howlett@Oracle.com>

diff --git a/Thoughts b/Thoughts
index ebba927f3016b49e24cc56f5816a560da3294f01..d3a49288fb50a58dc80422b52d4a5ba8661baaf9 100644 (file)
--- a/Thoughts
+++ b/Thoughts
@@ -178,34 +178,25 @@ necessary.  This means that it may be necessary for the node to the left to
 acquire entries from the node which would otherwise need to be split.  This
 would allow for two allocations (parent, and a single child) and an append
 instead of three allocations (parent, and two new children).  The parent would
-need to be a new node to avoid implying the incorrect range of slot 0.
+need to be a new node to avoid implying the incorrect range for slot 0.
 
 Coalescing should also keep allocating new nodes to a minimum.  To achieve the
-low allocation count goal, coalescing will attempt to allocate three new nodes
-and move entries to the left node.  If allocation fails, then coalescing should
-combine gaps between nodes by moving them to the start of the right node.  This
-can be done safely without an allocation by simply changing the parents pivot
-and setting any extra pivots in the left child to 0.  The fall-back case of
-moving gaps to the left is a special case since an RCU reader would hit the end
-of a node and correctly assume the last pivot + 1 to the maximum of this node
-is NULL.
-
-If there is enough space within the left node for the entire right node, then
-only two allocations are needed (parent and a single child) and, possibly, any
-ripple effects of combining the parent's right node.  This ripple effect will
-require 2-3 allocations per level depending on if the right nodes data can
-entirely be moved to the left node.  Upon having a single entry at any level,
-then that level can be removed entirely from the tree.  If there is a single
-entry for the 0 entry, then the entire tree can be collapsed into a single
-pointer.  Upon allocation failures, the node will continue to contain the
-XA_DELETED_ENTRY and the parent may require an XA_SKIP_ENTRY if a node is
-freed.  Any gaps that can be combined will be done at the start of a node.
-
-When coalescing, a value may be relocated to a different sub-tree.  In this
-case, a reader may already be on its way down and 'miss' the move.  To avoid
-this issue, the special value XA_RETRY_ENTRY is used to indicate a value has
-been moved and the walk operation must restart from the root node.
-
+low allocation count goal, coalescing will attempt to use a single node to
+combine both left and right nodes into a single node.  If this is possible,
+then the result will be a parent which contains two duplicate pivots of the
+right-most entry value and the right child will be replaced by an
+XA_SKIP_ENTRY.  Upon completion, the parent will need to be checked for
+coalescing as well.  If the left and the right nodes cannot fit into a single
+node, then the data is split evenly between both nodes, adjust the parent
+pivot, and fill the moved data with XA_RETRY_ENTRY values.  This will avoid
+needing to rebalance the right child and the parent would not need to be
+rebalanced.
+
+To avoid jitter between coalescing and splitting during a remove and insert
+operation, there is a need to keep the low water mark of coalescing and the
+high watermark of data resulting from a split operation.  It is worth noting
+that deleting a single entry may result in a NULL, XA_DELETED_ENTRY, NULL which
+means a node size can change by 2 with a single delete.
 
 Rebalance & Replacing
 ---------------------