#Addresses 311.

git-svn-id: file:///svn/tokudb@1997 c7de825b-a66e-492c-adef-691d508d4ae1

src/lock_tree/locktree.h

@@ -204,53 +204,56 @@ int toku_lt_acquire_read_lock(toku_lock_tree* tree, DB_TXN* txn,
                               const DBT* key, const DBT* data);
 
 /*
- * Acquires a read lock on a key range (or key/data range).  (Closed range).
- * Params:
- *      tree:           The lock tree for the db.
- *      txn:            The TOKU Transaction this lock is for.
- *      key_left:       The left end key of the range.
- *      data_left:     The left end data of the range.
- *      key_right:      The right end key of the range.
- *      data_right:    The right end data of the range.
- * Returns:
- *      0:                  Success.
- *      DB_LOCK_NOTGRANTED: If there is a conflict in getting the lock.
- *                          This can only happen if some other transaction has
- *                          a write lock that overlaps this range.
- *      EINVAL:             If (tree == NULL || txn == NULL ||
- *                              key_left == NULL || key_right == NULL) or
- *                             (tree->db is dupsort &&
- *                               (data_left == NULL || data_right == NULL)) or
- *                             (tree->db is nodup   &&
- *                               (data_left != NULL || data_right != NULL)) or
- *                             (tree->db is dupsort && key_left != data_left &&
- *                                  (key_left == toku_lt_infinity ||
- *                                   key_left == toku_lt_neg_infinity)) or
- *                             (tree->db is dupsort && key_right != data_right &&
- *                                  (key_right == toku_lt_infinity ||
- *                                   key_right == toku_lt_neg_infinity))
- *      EDOM:             In a DB_DUPSORT db:
- *                            If (key_left, data_left) >  (key_right, data_right) or
- *                          In a nodup db:      if (key_left) >  (key_right)
- *                          (According to the db's comparison functions.
- *      ENOMEM:             If adding the lock would exceed the maximum
- *                          memory allowed for payloads.
- * Asserts:
- *      The EINVAL and ERANGE cases described will use assert to abort instead of returning errors.
- *      If this library is ever exported to users, we will use error datas instead.
- * Memory:
- *      It is safe to free keys and datas after this call.
- *      If the lock tree needs to hold onto the key or data, it will make copies
- *      to its local memory.
- * *** Note that txn == NULL is not supported at this time.
+   Acquires a read lock on a key range (or key/data range).  (Closed range).
+
+   \param tree:           The lock tree for the db.
+   \param txn:            The TOKU Transaction this lock is for.
+   \param key_left:       The left end key of the range.
+   \param data_left:      The left end data of the range.
+   \param key_right:      The right end key of the range.
+   \param data_right:     The right end data of the range.
+
+   \return
+   - 0:                  Success.
+   - DB_LOCK_NOTGRANTED: If there is a conflict in getting the lock.
+                         This can only happen if some other transaction has
+                         a write lock that overlaps this range.
+   - EDOM:               In a DB_DUPSORT db:
+                         If (key_left, data_left) >  (key_right, data_right) or
+                         In a nodup db:      if (key_left) >  (key_right)
+                         (According to the db's comparison functions.)
+   - ENOMEM:             If adding the lock would exceed the maximum
+                         memory allowed for payloads.
+
+    The following is asserted, but if this library is ever exported to users,
+    EINVAL should be used instead:
+     If (tree == NULL || txn == NULL ||
+         key_left == NULL || key_right == NULL) or
+        (tree->db is dupsort &&
+          (data_left == NULL || data_right == NULL)) or
+        (tree->db is nodup   &&
+          (data_left != NULL || data_right != NULL)) or
+        (tree->db is dupsort && key_left != data_left &&
+             (key_left == toku_lt_infinity ||
+              key_left == toku_lt_neg_infinity)) or
+        (tree->db is dupsort && key_right != data_right &&
+             (key_right == toku_lt_infinity ||
+              key_right == toku_lt_neg_infinity))
+
+    Memory: It is safe to free keys and datas after this call.
+    If the lock tree needs to hold onto the key or data, it will make copies
+    to its local memory.
+
+    Note that txn == NULL is not supported at this time.
+
+    In BDB, txn can actually be NULL (mixed operations with transactions and 
+    no transactions). This can cause conflicts, nobody was unable (so far) 
+    to verify that MySQL does or does not use this.
  */
 int toku_lt_acquire_range_read_lock(toku_lock_tree* tree, DB_TXN* txn,
                                    const DBT* key_left,  const DBT* data_left,
                                    const DBT* key_right, const DBT* data_right);
 
- //In BDB, txn can actually be NULL (mixed operations with transactions and no transactions).
- //This can cause conflicts, I was unable (so far) to verify that MySQL does or does not use
- //this.
 /*
  * Acquires a write lock on a single key (or key/data).
  * Params: