bk commit into 4.1 tree (sergefp:1.2544)

[Sergey Petrunia]

Below is the list of changes that have just been committed into a local
4.1 repository of psergey. When psergey does a push these changes will
be propagated to the main repository and, within 24 hours after the
push, to the public repository.
For information on how to access the public repository
see http://dev.mysql.com/doc/mysql/en/installing-source-tree.html

ChangeSet@stripped, 2006-08-24 19:21:31+04:00, sergefp@stripped +1 -0
  Added comments for Item_ref and Item_direct_ref classes

  sql/item.h@stripped, 2006-08-24 19:21:29+04:00, sergefp@stripped +37 -0
    Added comments for Item_ref and Item_direct_ref classes

# This is a BitKeeper patch.  What follows are the unified diffs for the
# set of deltas contained in the patch.  The rest of the patch, the part
# that BitKeeper cares about, is below these diffs.
# User:	sergefp
# Host:	pslp.mylan
# Root:	/home/psergey/mysql-4.1-bug16255-review

--- 1.195/sql/item.h	2006-08-24 19:21:35 +04:00
+++ 1.196/sql/item.h	2006-08-24 19:21:35 +04:00
@@ -902,6 +902,33 @@
 };
 
 
+/*
+  Item_ref is used for table column/ named-select-list-entry references that
+  are located in the HAVING clause.
+
+  For example, for
+  
+    SELECT ... FROM t1 ... HAVING  ... t1.fieldX ...
+    
+  the shown "t1.fieldX" will be translated into Item_ref(Item_field(...)).
+  Item_ref class makes special arrangements to account for reference being
+  in the HAVING clause:
+
+   - References located in HAVING clause have special name resolution rules.
+   
+   - When the HAVING clause is evaluated, current table rows (located in 
+     st_table::record[0]) in general case do not contain rows of a group-by
+     row group being evaluated, so some_item_field->val_XXX() calls will
+     not return correct values, e.g. in the above example, we can't use the
+     return value of t1_fieldX_item_field->val_int() when evaluating the 
+     HAVING clause.  We must use val_int_result() call instead.
+
+  Note: the above is only psergey's understanding of the subject and may be
+        inaccurate.
+
+  TODO: figure out why Item_ref::val_*_result() are necessary.
+*/
+
 class Item_ref :public Item_ident
 {
 protected:
@@ -1002,7 +1029,17 @@
 /*
   The same as Item_ref, but get value from val_* family of method to get
   value of item on which it referred instead of result* family.
+
+  Item_direct_ref is same Item_ref except that Item_direct_ref::val_XXX()
+  methods use (*ref)->val_XXX() and not (*ref)->val_XXX_result(). 
+  
+  In other words, Item_direct_ref objects are just call redirectors. We use
+  them (and not copy Item* pointers) because most of "container" item classes
+  (e.g. Item_cond_and, Item_func) assume that they "own" Item objects they 
+  contain (NOTE: the last passage is only psergey's understanding and may be
+  inaccurate)
 */
+
 class Item_direct_ref :public Item_ref
 {
 public: