From: Mukund Sivaraman <muks@isc.org>
Date: Fri, 6 Sep 2013 04:08:14 +0000 (+0530)
Subject: [2750] Add comments in exchange() about asymmetric code
X-Git-Tag: bind10-1.2.0beta1-release~193^2~4^2~12
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=63a7f8bf4e61b69fd29a189f9bc683b5de0ce57b;p=thirdparty%2Fkea.git

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

diff --git a/src/lib/datasrc/memory/domaintree.h b/src/lib/datasrc/memory/domaintree.h
index 8a66be889e..4f7f71a430 100644
--- a/src/lib/datasrc/memory/domaintree.h
+++ b/src/lib/datasrc/memory/domaintree.h
@@ -666,16 +666,27 @@ 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>* 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.
+
+        // 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;