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 http://www.opensolaris.org/os/licensing. 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 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_destoy(). 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 AVL_ISIGN(a) (((a) > 0) - ((a) < 0)) 112 #define AVL_CMP(a, b) (((a) > (b)) - ((a) < (b))) 113 #define AVL_PCMP(a, b) \ 114 (((uintptr_t)(a) > (uintptr_t)(b)) - ((uintptr_t)(a) < (uintptr_t)(b))) 115 116 /* 117 * AVL comparator helpers 118 */ 119 #define AVL_ISIGN(a) (((a) > 0) - ((a) < 0)) 120 #define AVL_CMP(a, b) (((a) > (b)) - ((a) < (b))) 121 #define AVL_PCMP(a, b) \ 122 (((uintptr_t)(a) > (uintptr_t)(b)) - ((uintptr_t)(a) < (uintptr_t)(b))) 123 124 /* 125 * Type used for the root of the AVL tree. 126 */ 127 typedef struct avl_tree avl_tree_t; 128 129 /* 130 * The data nodes in the AVL tree must have a field of this type. 131 */ 132 typedef struct avl_node avl_node_t; 133 134 /* 135 * An opaque type used to locate a position in the tree where a node 136 * would be inserted. 137 */ 138 typedef uintptr_t avl_index_t; 139 140 141 /* 142 * Direction constants used for avl_nearest(). 143 */ 144 #define AVL_BEFORE (0) 145 #define AVL_AFTER (1) 146 147 148 /* 149 * Prototypes 150 * 151 * Where not otherwise mentioned, "void *" arguments are a pointer to the 152 * user data structure which must contain a field of type avl_node_t. 153 * 154 * Also assume the user data structures looks like: 155 * stuct my_type { 156 * ... 157 * avl_node_t my_link; 158 * ... 159 * }; 160 */ 161 162 /* 163 * Initialize an AVL tree. Arguments are: 164 * 165 * tree - the tree to be initialized 166 * compar - function to compare two nodes, it must return exactly: -1, 0, or +1 167 * -1 for <, 0 for ==, and +1 for > 168 * size - the value of sizeof(struct my_type) 169 * offset - the value of OFFSETOF(struct my_type, my_link) 170 */ 171 extern void avl_create(avl_tree_t *tree, 172 int (*compar) (const void *, const void *), size_t size, size_t offset); 173 174 175 /* 176 * Find a node with a matching value in the tree. Returns the matching node 177 * found. If not found, it returns NULL and then if "where" is not NULL it sets 178 * "where" for use with avl_insert() or avl_nearest(). 179 * 180 * node - node that has the value being looked for 181 * where - position for use with avl_nearest() or avl_insert(), may be NULL 182 */ 183 extern void *avl_find(avl_tree_t *tree, const void *node, avl_index_t *where); 184 185 /* 186 * Insert a node into the tree. 187 * 188 * node - the node to insert 189 * where - position as returned from avl_find() 190 */ 191 extern void avl_insert(avl_tree_t *tree, void *node, avl_index_t where); 192 193 /* 194 * Insert "new_data" in "tree" in the given "direction" either after 195 * or before the data "here". 196 * 197 * This might be useful for avl clients caching recently accessed 198 * data to avoid doing avl_find() again for insertion. 199 * 200 * new_data - new data to insert 201 * here - existing node in "tree" 202 * direction - either AVL_AFTER or AVL_BEFORE the data "here". 203 */ 204 extern void avl_insert_here(avl_tree_t *tree, void *new_data, void *here, 205 int direction); 206 207 208 /* 209 * Return the first or last valued node in the tree. Will return NULL 210 * if the tree is empty. 211 * 212 */ 213 extern void *avl_first(avl_tree_t *tree); 214 extern void *avl_last(avl_tree_t *tree); 215 216 217 /* 218 * Return the next or previous valued node in the tree. 219 * AVL_NEXT() will return NULL if at the last node. 220 * AVL_PREV() will return NULL if at the first node. 221 * 222 * node - the node from which the next or previous node is found 223 */ 224 #define AVL_NEXT(tree, node) avl_walk(tree, node, AVL_AFTER) 225 #define AVL_PREV(tree, node) avl_walk(tree, node, AVL_BEFORE) 226 227 228 /* 229 * Find the node with the nearest value either greater or less than 230 * the value from a previous avl_find(). Returns the node or NULL if 231 * there isn't a matching one. 232 * 233 * where - position as returned from avl_find() 234 * direction - either AVL_BEFORE or AVL_AFTER 235 * 236 * EXAMPLE get the greatest node that is less than a given value: 237 * 238 * avl_tree_t *tree; 239 * struct my_data look_for_value = {....}; 240 * struct my_data *node; 241 * struct my_data *less; 242 * avl_index_t where; 243 * 244 * node = avl_find(tree, &look_for_value, &where); 245 * if (node != NULL) 246 * less = AVL_PREV(tree, node); 247 * else 248 * less = avl_nearest(tree, where, AVL_BEFORE); 249 */ 250 extern void *avl_nearest(avl_tree_t *tree, avl_index_t where, int direction); 251 252 253 /* 254 * Add a single node to the tree. 255 * The node must not be in the tree, and it must not 256 * compare equal to any other node already in the tree. 257 * 258 * node - the node to add 259 */ 260 extern void avl_add(avl_tree_t *tree, void *node); 261 262 263 /* 264 * Remove a single node from the tree. The node must be in the tree. 265 * 266 * node - the node to remove 267 */ 268 extern void avl_remove(avl_tree_t *tree, void *node); 269 270 /* 271 * Reinsert a node only if its order has changed relative to its nearest 272 * neighbors. To optimize performance avl_update_lt() checks only the previous 273 * node and avl_update_gt() checks only the next node. Use avl_update_lt() and 274 * avl_update_gt() only if you know the direction in which the order of the 275 * node may change. 276 */ 277 extern boolean_t avl_update(avl_tree_t *, void *); 278 extern boolean_t avl_update_lt(avl_tree_t *, void *); 279 extern boolean_t avl_update_gt(avl_tree_t *, void *); 280 281 /* 282 * Swaps the contents of the two trees. 283 */ 284 extern void avl_swap(avl_tree_t *tree1, avl_tree_t *tree2); 285 286 /* 287 * Return the number of nodes in the tree 288 */ 289 extern ulong_t avl_numnodes(avl_tree_t *tree); 290 291 /* 292 * Return B_TRUE if there are zero nodes in the tree, B_FALSE otherwise. 293 */ 294 extern boolean_t avl_is_empty(avl_tree_t *tree); 295 296 /* 297 * Used to destroy any remaining nodes in a tree. The cookie argument should 298 * be initialized to NULL before the first call. Returns a node that has been 299 * removed from the tree and may be free()'d. Returns NULL when the tree is 300 * empty. 301 * 302 * Once you call avl_destroy_nodes(), you can only continuing calling it and 303 * finally avl_destroy(). No other AVL routines will be valid. 304 * 305 * cookie - a "void *" used to save state between calls to avl_destroy_nodes() 306 * 307 * EXAMPLE: 308 * avl_tree_t *tree; 309 * struct my_data *node; 310 * void *cookie; 311 * 312 * cookie = NULL; 313 * while ((node = avl_destroy_nodes(tree, &cookie)) != NULL) 314 * free(node); 315 * avl_destroy(tree); 316 */ 317 extern void *avl_destroy_nodes(avl_tree_t *tree, void **cookie); 318 319 320 /* 321 * Final destroy of an AVL tree. Arguments are: 322 * 323 * tree - the empty tree to destroy 324 */ 325 extern void avl_destroy(avl_tree_t *tree); 326 327 328 329 #ifdef __cplusplus 330 } 331 #endif 332 333 #endif /* _AVL_H */ 334