include/sys/avl.h

   1 /*
   2  * CDDL HEADER START
   3  *
   4  * The contents of this file are subject to the terms of the
   5  * Common Development and Distribution License (the "License").
   6  * You may not use this file except in compliance with the License.
   7  *
   8  * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
   9  * or https://opensource.org/licenses/CDDL-1.0.
  10  * See the License for the specific language governing permissions
  11  * and limitations under the License.
  12  *
  13  * When distributing Covered Code, include this CDDL HEADER in each
  14  * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
  15  * If applicable, add the following below this CDDL HEADER, with the
  16  * fields enclosed by brackets "[]" replaced with your own identifying
  17  * information: Portions Copyright [yyyy] [name of copyright owner]
  18  *
  19  * CDDL HEADER END
  20  */
  21 /*
  22  * Copyright 2009 Sun Microsystems, Inc.  All rights reserved.
  23  * Use is subject to license terms.
  24  */
  25
  26 /*
  27  * Copyright (c) 2014 by Delphix. All rights reserved.
  28  */
  29
  30 #ifndef _AVL_H
  31 #define _AVL_H extern __attribute__((visibility("default")))
  32
  33 /*
  34  * This is a private header file.  Applications should not directly include
  35  * this file.
  36  */
  37
  38 #ifdef  __cplusplus
  39 extern "C" {
  40 #endif
  41
  42 #include <sys/types.h>
  43 #include <sys/avl_impl.h>
  44
  45 /*
  46  * This is a generic implementation of AVL trees for use in the Solaris kernel.
  47  * The interfaces provide an efficient way of implementing an ordered set of
  48  * data structures.
  49  *
  50  * AVL trees provide an alternative to using an ordered linked list. Using AVL
  51  * trees will usually be faster, however they requires more storage. An ordered
  52  * linked list in general requires 2 pointers in each data structure. The
  53  * AVL tree implementation uses 3 pointers. The following chart gives the
  54  * approximate performance of operations with the different approaches:
  55  *
  56  *      Operation        Link List      AVL tree
  57  *      ---------        --------       --------
  58  *      lookup             O(n)         O(log(n))
  59  *
  60  *      insert 1 node    constant       constant
  61  *
  62  *      delete 1 node    constant       between constant and O(log(n))
  63  *
  64  *      delete all nodes   O(n)         O(n)
  65  *
  66  *      visit the next
  67  *      or prev node     constant       between constant and O(log(n))
  68  *
  69  *
  70  * The data structure nodes are anchored at an "avl_tree_t" (the equivalent
  71  * of a list header) and the individual nodes will have a field of
  72  * type "avl_node_t" (corresponding to list pointers).
  73  *
  74  * The type "avl_index_t" is used to indicate a position in the list for
  75  * certain calls.
  76  *
  77  * The usage scenario is generally:
  78  *
  79  * 1. Create the list/tree with: avl_create()
  80  *
  81  * followed by any mixture of:
  82  *
  83  * 2a. Insert nodes with: avl_add(), or avl_find() and avl_insert()
  84  *
  85  * 2b. Visited elements with:
  86  *       avl_first() - returns the lowest valued node
  87  *       avl_last() - returns the highest valued node
  88  *       AVL_NEXT() - given a node go to next higher one
  89  *       AVL_PREV() - given a node go to previous lower one
  90  *
  91  * 2c.  Find the node with the closest value either less than or greater
  92  *      than a given value with avl_nearest().
  93  *
  94  * 2d. Remove individual nodes from the list/tree with avl_remove().
  95  *
  96  * and finally when the list is being destroyed
  97  *
  98  * 3. Use avl_destroy_nodes() to quickly process/free up any remaining nodes.
  99  *    Note that once you use avl_destroy_nodes(), you can no longer
 100  *    use any routine except avl_destroy_nodes() and avl_destroy().
 101  *
 102  * 4. Use avl_destroy() to destroy the AVL tree itself.
 103  *
 104  * Any locking for multiple thread access is up to the user to provide, just
 105  * as is needed for any linked list implementation.
 106  */
 107
 108 /*
 109  * AVL comparator helpers
 110  */
 111 #define TREE_ISIGN(a)   (((a) > 0) - ((a) < 0))
 112 #define TREE_CMP(a, b)  (((a) > (b)) - ((a) < (b)))
 113 #define TREE_PCMP(a, b) \
 114         (((uintptr_t)(a) > (uintptr_t)(b)) - ((uintptr_t)(a) < (uintptr_t)(b)))
 115
 116 /*
 117  * Type used for the root of the AVL tree.
 118  */
 119 typedef struct avl_tree avl_tree_t;
 120
 121 /*
 122  * The data nodes in the AVL tree must have a field of this type.
 123  */
 124 typedef struct avl_node avl_node_t;
 125
 126 /*
 127  * An opaque type used to locate a position in the tree where a node
 128  * would be inserted.
 129  */
 130 typedef uintptr_t avl_index_t;
 131
 132
 133 /*
 134  * Direction constants used for avl_nearest().
 135  */
 136 #define AVL_BEFORE      (0)
 137 #define AVL_AFTER       (1)
 138
 139
 140 /*
 141  * Prototypes
 142  *
 143  * Where not otherwise mentioned, "void *" arguments are a pointer to the
 144  * user data structure which must contain a field of type avl_node_t.
 145  *
 146  * Also assume the user data structures looks like:
 147  *      struct my_type {
 148  *              ...
 149  *              avl_node_t      my_link;
 150  *              ...
 151  *      };
 152  */
 153
 154 /*
 155  * Initialize an AVL tree. Arguments are:
 156  *
 157  * tree   - the tree to be initialized
 158  * compar - function to compare two nodes, it must return exactly: -1, 0, or +1
 159  *          -1 for <, 0 for ==, and +1 for >
 160  * size   - the value of sizeof(struct my_type)
 161  * offset - the value of OFFSETOF(struct my_type, my_link)
 162  */
 163 _AVL_H void avl_create(avl_tree_t *tree,
 164         int (*compar) (const void *, const void *), size_t size, size_t offset);
 165
 166
 167 /*
 168  * Find a node with a matching value in the tree. Returns the matching node
 169  * found. If not found, it returns NULL and then if "where" is not NULL it sets
 170  * "where" for use with avl_insert() or avl_nearest().
 171  *
 172  * node   - node that has the value being looked for
 173  * where  - position for use with avl_nearest() or avl_insert(), may be NULL
 174  */
 175 _AVL_H void *avl_find(avl_tree_t *tree, const void *node, avl_index_t *where);
 176
 177 /*
 178  * Insert a node into the tree.
 179  *
 180  * node   - the node to insert
 181  * where  - position as returned from avl_find()
 182  */
 183 _AVL_H void avl_insert(avl_tree_t *tree, void *node, avl_index_t where);
 184
 185 /*
 186  * Insert "new_data" in "tree" in the given "direction" either after
 187  * or before the data "here".
 188  *
 189  * This might be useful for avl clients caching recently accessed
 190  * data to avoid doing avl_find() again for insertion.
 191  *
 192  * new_data     - new data to insert
 193  * here         - existing node in "tree"
 194  * direction    - either AVL_AFTER or AVL_BEFORE the data "here".
 195  */
 196 _AVL_H void avl_insert_here(avl_tree_t *tree, void *new_data, void *here,
 197     int direction);
 198
 199
 200 /*
 201  * Return the first or last valued node in the tree. Will return NULL
 202  * if the tree is empty.
 203  *
 204  */
 205 _AVL_H void *avl_first(avl_tree_t *tree);
 206 _AVL_H void *avl_last(avl_tree_t *tree);
 207
 208
 209 /*
 210  * Return the next or previous valued node in the tree.
 211  * AVL_NEXT() will return NULL if at the last node.
 212  * AVL_PREV() will return NULL if at the first node.
 213  *
 214  * node   - the node from which the next or previous node is found
 215  */
 216 #define AVL_NEXT(tree, node)    avl_walk(tree, node, AVL_AFTER)
 217 #define AVL_PREV(tree, node)    avl_walk(tree, node, AVL_BEFORE)
 218
 219
 220 /*
 221  * Find the node with the nearest value either greater or less than
 222  * the value from a previous avl_find(). Returns the node or NULL if
 223  * there isn't a matching one.
 224  *
 225  * where     - position as returned from avl_find()
 226  * direction - either AVL_BEFORE or AVL_AFTER
 227  *
 228  * EXAMPLE get the greatest node that is less than a given value:
 229  *
 230  *      avl_tree_t *tree;
 231  *      struct my_data look_for_value = {....};
 232  *      struct my_data *node;
 233  *      struct my_data *less;
 234  *      avl_index_t where;
 235  *
 236  *      node = avl_find(tree, &look_for_value, &where);
 237  *      if (node != NULL)
 238  *              less = AVL_PREV(tree, node);
 239  *      else
 240  *              less = avl_nearest(tree, where, AVL_BEFORE);
 241  */
 242 _AVL_H void *avl_nearest(avl_tree_t *tree, avl_index_t where, int direction);
 243
 244
 245 /*
 246  * Add a single node to the tree.
 247  * The node must not be in the tree, and it must not
 248  * compare equal to any other node already in the tree.
 249  *
 250  * node   - the node to add
 251  */
 252 _AVL_H void avl_add(avl_tree_t *tree, void *node);
 253
 254
 255 /*
 256  * Remove a single node from the tree.  The node must be in the tree.
 257  *
 258  * node   - the node to remove
 259  */
 260 _AVL_H void avl_remove(avl_tree_t *tree, void *node);
 261
 262 /*
 263  * Reinsert a node only if its order has changed relative to its nearest
 264  * neighbors. To optimize performance avl_update_lt() checks only the previous
 265  * node and avl_update_gt() checks only the next node. Use avl_update_lt() and
 266  * avl_update_gt() only if you know the direction in which the order of the
 267  * node may change.
 268  */
 269 _AVL_H boolean_t avl_update(avl_tree_t *, void *);
 270 _AVL_H boolean_t avl_update_lt(avl_tree_t *, void *);
 271 _AVL_H boolean_t avl_update_gt(avl_tree_t *, void *);
 272
 273 /*
 274  * Swaps the contents of the two trees.
 275  */
 276 _AVL_H void avl_swap(avl_tree_t *tree1, avl_tree_t *tree2);
 277
 278 /*
 279  * Return the number of nodes in the tree
 280  */
 281 _AVL_H ulong_t avl_numnodes(avl_tree_t *tree);
 282
 283 /*
 284  * Return B_TRUE if there are zero nodes in the tree, B_FALSE otherwise.
 285  */
 286 _AVL_H boolean_t avl_is_empty(avl_tree_t *tree);
 287
 288 /*
 289  * Used to destroy any remaining nodes in a tree. The cookie argument should
 290  * be initialized to NULL before the first call. Returns a node that has been
 291  * removed from the tree and may be free()'d. Returns NULL when the tree is
 292  * empty.
 293  *
 294  * Once you call avl_destroy_nodes(), you can only continuing calling it and
 295  * finally avl_destroy(). No other AVL routines will be valid.
 296  *
 297  * cookie - a "void *" used to save state between calls to avl_destroy_nodes()
 298  *
 299  * EXAMPLE:
 300  *      avl_tree_t *tree;
 301  *      struct my_data *node;
 302  *      void *cookie;
 303  *
 304  *      cookie = NULL;
 305  *      while ((node = avl_destroy_nodes(tree, &cookie)) != NULL)
 306  *              free(node);
 307  *      avl_destroy(tree);
 308  */
 309 _AVL_H void *avl_destroy_nodes(avl_tree_t *tree, void **cookie);
 310
 311
 312 /*
 313  * Final destroy of an AVL tree. Arguments are:
 314  *
 315  * tree   - the empty tree to destroy
 316  */
 317 _AVL_H void avl_destroy(avl_tree_t *tree);
 318
 319
 320
 321 #ifdef  __cplusplus
 322 }
 323 #endif
 324
 325 #endif  /* _AVL_H */