BIND 10 trac2750, updated. 63a7f8bf4e61b69fd29a189f9bc683b5de0ce57b [2750] Add comments in exchange() about asymmetric code

[BIND 10 source code commits]

The branch, trac2750 has been updated
       via  63a7f8bf4e61b69fd29a189f9bc683b5de0ce57b (commit)
       via  8090d2c5186a96d80378072761625da2d8d421b0 (commit)
      from  05b3886971fb003b0bbd735975bbbf0c38a1970c (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 63a7f8bf4e61b69fd29a189f9bc683b5de0ce57b
Author: Mukund Sivaraman <muks at isc.org>
Date:   Fri Sep 6 09:38:14 2013 +0530

    [2750] Add comments in exchange() about asymmetric code

commit 8090d2c5186a96d80378072761625da2d8d421b0
Author: Mukund Sivaraman <muks at isc.org>
Date:   Fri Sep 6 09:37:02 2013 +0530

    [2750] Rename variable to lower

-----------------------------------------------------------------------

Summary of changes:
 src/lib/datasrc/memory/domaintree.h |   63 ++++++++++++++++++++---------------
 1 file changed, 37 insertions(+), 26 deletions(-)

-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/memory/domaintree.h b/src/lib/datasrc/memory/domaintree.h
index 99607ca..4f7f71a 100644
--- a/src/lib/datasrc/memory/domaintree.h
+++ b/src/lib/datasrc/memory/domaintree.h
@@ -666,58 +666,69 @@ private:
         }
     }
 
-    /// \brief Exchanges the location of two nodes. Their data remain
-    /// the same, but their location in the tree, colors and sub-tree
-    /// root status may change. Note that this is different from
-    /// std::swap()-like behavior.
+    /// \brief Exchanges the location of two nodes (this and
+    /// lower). Their data remain the same, but their location in the
+    /// tree, colors and sub-tree root status may change. Note that this
+    /// is different from std::swap()-like behavior.
+    ///
+    /// IMPORTANT: A necessary pre-condition is that lower node must be
+    /// at a lower level in the tree than this node. This method is
+    /// primarily used in remove() and this pre-condition is followed
+    /// there.
     ///
     /// This method doesn't throw any exceptions.
-    void exchange(DomainTreeNode<T>* other, DomainTreeNodePtr* root_ptr) {
+    void exchange(DomainTreeNode<T>* lower, DomainTreeNodePtr* root_ptr) {
         // Swap the pointers first. down should not be swapped as it
         // belongs to the node's data, and not to its position in the
         // tree.
-        std::swap(left_, other->left_);
-        if (other->getLeft() == other) {
-            other->left_ = this;
+
+        // NOTE: The conditions following the swaps below are
+        // asymmetric. We only need to check this for the lower node, as
+        // it can be a direct child of this node. The reverse is not
+        // possible.
+
+        std::swap(left_, lower->left_);
+        if (lower->getLeft() == lower) {
+            lower->left_ = this;
         }
 
-        std::swap(right_, other->right_);
-        if (other->getRight() == other) {
-            other->right_ = this;
+        std::swap(right_, lower->right_);
+        if (lower->getRight() == lower) {
+            lower->right_ = this;
         }
 
-        std::swap(parent_, other->parent_);
+        std::swap(parent_, lower->parent_);
         if (getParent() == this) {
-            parent_ = other;
+            parent_ = lower;
         }
 
         // Update FLAG_RED and FLAG_SUBTREE_ROOT as these two are
         // associated with the node's position.
         const DomainTreeNodeColor this_color = getColor();
         const bool this_is_subtree_root = isSubTreeRoot();
-        const DomainTreeNodeColor other_color = other->getColor();
-        const bool other_is_subtree_root = other->isSubTreeRoot();
+        const DomainTreeNodeColor lower_color = lower->getColor();
+        const bool lower_is_subtree_root = lower->isSubTreeRoot();
 
-        other->setColor(this_color);
-        setColor(other_color);
+        lower->setColor(this_color);
+        setColor(lower_color);
 
-        setSubTreeRoot(other_is_subtree_root);
-        other->setSubTreeRoot(this_is_subtree_root);
+        setSubTreeRoot(lower_is_subtree_root);
+        lower->setSubTreeRoot(this_is_subtree_root);
 
-        other->setParentChild(this, other, root_ptr);
+        lower->setParentChild(this, lower, root_ptr);
 
-        if (getParent()->getLeft() == other) {
+        if (getParent()->getLeft() == lower) {
             getParent()->left_ = this;
-        } else if (getParent()->getRight() == other) {
+        } else if (getParent()->getRight() == lower) {
             getParent()->right_ = this;
         }
 
-        if (other->getRight()) {
-            other->getRight()->parent_ = other;
+        if (lower->getRight()) {
+            lower->getRight()->parent_ = lower;
         }
 
-        if (other->getLeft()) {
-            other->getLeft()->parent_ = other;
+        if (lower->getLeft()) {
+            lower->getLeft()->parent_ = lower;
         }
     }