Skip to content

M
MariaDB
Commit eeffcefd authored by Yoni Fogel's avatar Yoni Fogel
Browse files
Options

Lock tree, range tree documentation. 

git-svn-id: file:///svn/tokudb@2331 c7de825b-a66e-492c-adef-691d508d4ae1
parent e085cb5a
Hide whitespace changes
Inline Side-by-side
Showing with 74 additions and 69 deletions
src/range_tree/rangetree.h
View file @ eeffcefd
......@@ -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,
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment
GitLab Nexedi Edition | About GitLab | About Nexedi | 沪ICP备2021021310号-2 | 沪ICP备2021021310号-7