Lock tree, range tree documentation.

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

src/range_tree/rangetree.h

@@ -30,8 +30,6 @@ typedef struct __toku_point toku_point;
 
 /** \brief Range with value
     Represents a range of data with an associated value.
-    Parameters are never modified on failure with the exception of
-    buf and buflen.
  */
 typedef struct {
 	toku_point* left;  /**< Left end-point */
@@ -39,6 +37,9 @@ typedef struct {
 	DB_TXN*     data;  /**< Data associated with the range */
 } toku_range;
 
+/** \brief Parameters are never modified on failure with the exception of
+    buf and buflen.
+ */
 struct __toku_range_tree;
 
 /** Export the internal representation to a sensible name */
@@ -59,21 +60,21 @@ int toku_rt_get_allow_overlaps(toku_range_tree* tree, BOOL* allowed);
 /**
     Creates a range tree.
 
-    \param ptree          Points to the new range tree if create is successful 
-    \param end_cmp        User provided function to compare end points.
-                          Return value conforms to cmp in qsort(3). 
-                          It must be commutative.
-    \param data_cmp       User provided function to compare data values.
-                          Return value conforms to cmp in qsort(3). 
-    \param allow_overlaps Whether ranges in this range tree are permitted 
-                          to overlap. 
-    \param user_malloc    A user provided malloc(3) function.
-    \param user_free      A user provided free(3) function.
-    \param user_realloc   A user provided realloc(3) function.
+    \param ptree            Points to the new range tree if create is successful 
+    \param end_cmp          User provided function to compare end points.
+                            Return value conforms to cmp in qsort(3). 
+                            It is assumed to define a total order.
+    \param data_cmp         User provided function to compare data values.
+                            Return value conforms to cmp in qsort(3). 
+    \param allow_overlaps   Whether ranges in this range tree are permitted 
+                            to overlap. 
+    \param user_malloc      A user provided malloc(3) function.
+    \param user_free        A user provided free(3) function.
+    \param user_realloc     A user provided realloc(3) function.
 
     \return
-    - 0:              Success.
-    - EINVAL:         If any pointer argument is NULL.
+    - 0:                    Success.
+    - EINVAL:               If any pointer argument is NULL.
     - Other exit codes may be forwarded from underlying system calls. */
 int toku_rt_create(toku_range_tree** ptree,
                    int (*end_cmp)(toku_point*,toku_point*), 
@@ -84,38 +85,42 @@ int toku_rt_create(toku_range_tree** ptree,
 
 /**
     Destroys and frees a range tree.
+
+    \param tree             The range tree to close.
+    
     \return
-    - 0:              Success.
-    - EINVAL:         If tree is NULL.
+    - 0:                    Success.
+    - EINVAL:               If tree is NULL.
  */
-int toku_rt_close(toku_range_tree* tree  /**< The range tree to free */);
+int toku_rt_close(toku_range_tree* tree);
 
 /**
-   Finds ranges in the range tree that overlap a query range.
-
-   \param tree     The range tree to search in. 
-   \param query    The range to query. range.data must be NULL. 
-   \param k        The maximum number of ranges to return. 
-                   The special value '0' is used to request ALL overlapping 
-                   ranges. 
-   \param buf      A pointer to the buffer used to return ranges.
-                   The buffer will be increased using realloc(3) if necessary.
-                   NOTE: buf must have been dynamically allocated i.e. via 
-                   malloc(3), calloc(3), etc.
-                   The buffer will not be modified unless it is too small.
-   \param buflen   A pointer to the lenfth of the buffer.  
-                   If the buffer is increased, then buflen will be updated. 
-   \param numfound The number of ranges found. This will necessarily be <= k.
-                   If k != 0 && numfound == k, there may be additional
-                   ranges that overlap the queried range but were skipped
-                   to accomodate the request of k. 
-
-   \return
-   - 0:              Success.
-   - EINVAL:         If any pointer argument is NULL. If range.data != NULL.
+    Finds ranges in the range tree that overlap a query range.
+
+    \param tree     The range tree to search in. 
+    \param query    The range to query. range.data must be NULL. 
+    \param k        The maximum number of ranges to return. 
+                    The special value '0' is used to request ALL overlapping 
+                    ranges. 
+    \param buf      A pointer to the buffer used to return ranges.
+                    The buffer will be increased using realloc(3) if necessary.
+                    NOTE: buf must have been dynamically allocated i.e. via 
+                    malloc(3), calloc(3), etc.
+                    The buffer will not be modified unless it is too small.
+    \param buflen   A pointer to the current length of the buffer.  
+                    If the buffer is increased, then buflen will be updated. 
+    \param numfound The number of ranges found. This will necessarily be <= k
+                    unless k == 0.
+                    If k != 0 && numfound == k, there may be additional
+                    ranges that overlap the queried range but were skipped
+                    to accomodate the request of k. 
+
+    \return
+    - 0:             Success.
+    - EINVAL:        If any pointer argument is NULL. If range.data != NULL.
                      If buflen == 0.
-   - Other exit codes may be forwarded from underlying system calls but only
-     if buf is not large enough.
+    - Other exit codes may be forwarded from underlying system calls if buf is
+     not large enough.
 
     Growth direction: It may be useful in the future to add an extra out 
     parameter to specify whether more elements exist in the tree that overlap 
@@ -128,16 +133,16 @@ int toku_rt_find(toku_range_tree* tree,toku_range* query, u_int32_t k,
 /**
     Inserts a range into the range tree.
 
-    \param tree            The range tree to insert into.
-    \param range           The range to insert.
+    \param tree     The range tree to insert into.
+    \param range    The range to insert.
 
     \return
-    - 0:              Success.
-    - EINVAL:         If any pointer argument is NULL.
-    - EDOM:           If the exact range (left, right, and data) already
-                      exists in the tree.
-                      If an overlapping range exists in the tree and
-                      allow_overlaps == FALSE.
+    - 0:            Success.
+    - EINVAL:       If any pointer argument is NULL.
+    - EDOM:         If an equivalent range (left, right, and data according to
+                    end_cmp and data_cmp) already exists in the tree.
+                    If an overlapping range exists in the tree and
+                    allow_overlaps == FALSE.
     - Other exit codes may be forwarded from underlying system calls.
  */
 int toku_rt_insert(toku_range_tree* tree, toku_range* range);
@@ -145,14 +150,14 @@ int toku_rt_insert(toku_range_tree* tree, toku_range* range);
 /**
     Deletes a range from the range tree.
 
-    \param tree            The range tree to delete from.
-    \param range           The range to delete.
+    \param tree     The range tree to delete from.
+    \param range    The range to delete.
 
     \return
-    - 0:              Success.
-    - EINVAL:         If any pointer argument is NULL.
-    - EDOM:           If the exact range (left, right, and data) did
-                      not exist in the tree.
+    - 0:            Success.
+    - EINVAL:       If any pointer argument is NULL.
+    - EDOM:         If the exact range (left, right, and data) did
+                    not exist in the tree.
  */
 int toku_rt_delete(toku_range_tree* tree, toku_range* range);
 
@@ -161,18 +166,18 @@ int toku_rt_delete(toku_range_tree* tree, toku_range* range);
     completely to the left of the query point according to end_cmp.
     This operation is only defined if allow_overlaps == FALSE.
 
-    \param tree            The range tree to search in.
-    \param point           The point to query.  Must be a valid argument to
-                           end_cmp.
-    \param pred            A buffer to return the predecessor.
-    \param wasfound        Whether a predecessor was found.
-                           If no range is strictly to the left of the query 
-                           point this will be false.
+    \param tree         The range tree to search in.
+    \param point        The point to query.  Must be a valid argument to
+                        end_cmp.
+    \param pred         A buffer to return the predecessor.
+    \param wasfound     Whether a predecessor was found.
+                        If no range is strictly to the left of the query 
+                        point this will be false.
 
     \return
-    - 0:              Success.
-    - EINVAL:         If any pointer argument is NULL.
-                      If tree allows overlaps.
+    - 0:                Success.
+    - EINVAL:           If any pointer argument is NULL.
+                        If tree allows overlaps.
     - Other exit codes may be forwarded from underlying system calls.
  */
 int toku_rt_predecessor(toku_range_tree* tree, toku_point* point,
@@ -192,9 +197,9 @@ int toku_rt_predecessor(toku_range_tree* tree, toku_point* point,
                         this will be false.
 
     \return
-    - 0:              Success.
-    - EINVAL:         If any pointer argument is NULL.
-                      If tree allows overlaps.
+    - 0:                Success.
+    - EINVAL:           If any pointer argument is NULL.
+                        If tree allows overlaps.
     - Other exit codes may be forwarded from underlying system calls.
  */
 int toku_rt_successor(toku_range_tree* tree, toku_point* point,