xref: /onnv-gate/usr/src/cmd/filebench/common/fb_avl.h (revision 9513:5dc53d16bc1b)
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 #ifndef	FB_AVL_H
27 #define	FB_AVL_H
28 
29 /*
30  * derived from  Solaris' sys/avl.h and sys/avl_impl.h
31  */
32 
33 #ifdef	__cplusplus
34 extern "C" {
35 #endif
36 
37 #include <sys/types.h>
38 
39 /*
40  * generic AVL tree implementation for FileBench use
41  *
42  * The interfaces provide an efficient way of implementing an ordered set of
43  * data structures.
44  *
45  * AVL trees provide an alternative to using an ordered linked list. Using AVL
46  * trees will usually be faster, however they requires more storage. An ordered
47  * linked list in general requires 2 pointers in each data structure. The
48  * AVL tree implementation uses 3 pointers. The following chart gives the
49  * approximate performance of operations with the different approaches:
50  *
51  *	Operation	 Link List	AVL tree
52  *	---------	 --------	--------
53  *	lookup		   O(n)		O(log(n))
54  *
55  *	insert 1 node	 constant	constant
56  *
57  *	delete 1 node	 constant	between constant and O(log(n))
58  *
59  *	delete all nodes   O(n)		O(n)
60  *
61  *	visit the next
62  *	or prev node	 constant	between constant and O(log(n))
63  *
64  *
65  * There are 5 pieces of information stored for each node in an AVL tree
66  *
67  * 	pointer to less than child
68  * 	pointer to greater than child
69  * 	a pointer to the parent of this node
70  *	an indication  [0/1]  of which child I am of my parent
71  * 	a "balance" (-1, 0, +1)  indicating which child tree is taller
72  *
73  * Since they only need 3 bits, the last two fields are packed into the
74  * bottom bits of the parent pointer on 64 bit machines to save on space.
75  */
76 
77 #ifndef _LP64
78 
79 struct avl_node {
80 	struct avl_node *avl_child[2];	/* left/right children */
81 	struct avl_node *avl_parent;	/* this node's parent */
82 	unsigned short avl_child_index;	/* my index in parent's avl_child[] */
83 	short avl_balance;		/* balance value: -1, 0, +1 */
84 };
85 
86 #define	AVL_XPARENT(n)		((n)->avl_parent)
87 #define	AVL_SETPARENT(n, p)	((n)->avl_parent = (p))
88 
89 #define	AVL_XCHILD(n)		((n)->avl_child_index)
90 #define	AVL_SETCHILD(n, c)	((n)->avl_child_index = (unsigned short)(c))
91 
92 #define	AVL_XBALANCE(n)		((n)->avl_balance)
93 #define	AVL_SETBALANCE(n, b)	((n)->avl_balance = (short)(b))
94 
95 #else /* _LP64 */
96 
97 /*
98  * for 64 bit machines, avl_pcb contains parent pointer, balance and child_index
99  * values packed in the following manner:
100  *
101  * |63                                  3|        2        |1          0 |
102  * |-------------------------------------|-----------------|-------------|
103  * |      avl_parent hi order bits       | avl_child_index | avl_balance |
104  * |                                     |                 |     + 1     |
105  * |-------------------------------------|-----------------|-------------|
106  *
107  */
108 struct avl_node {
109 	struct avl_node *avl_child[2];	/* left/right children nodes */
110 	uintptr_t avl_pcb;		/* parent, child_index, balance */
111 };
112 
113 /*
114  * macros to extract/set fields in avl_pcb
115  *
116  * pointer to the parent of the current node is the high order bits
117  */
118 #define	AVL_XPARENT(n)		((struct avl_node *)((n)->avl_pcb & ~7))
119 #define	AVL_SETPARENT(n, p)						\
120 	((n)->avl_pcb = (((n)->avl_pcb & 7) | (uintptr_t)(p)))
121 
122 /*
123  * index of this node in its parent's avl_child[]: bit #2
124  */
125 #define	AVL_XCHILD(n)		(((n)->avl_pcb >> 2) & 1)
126 #define	AVL_SETCHILD(n, c)						\
127 	((n)->avl_pcb = (uintptr_t)(((n)->avl_pcb & ~4) | ((c) << 2)))
128 
129 /*
130  * balance indication for a node, lowest 2 bits. A valid balance is
131  * -1, 0, or +1, and is encoded by adding 1 to the value to get the
132  * unsigned values of 0, 1, 2.
133  */
134 #define	AVL_XBALANCE(n)		((int)(((n)->avl_pcb & 3) - 1))
135 #define	AVL_SETBALANCE(n, b)						\
136 	((n)->avl_pcb = (uintptr_t)((((n)->avl_pcb & ~3) | ((b) + 1))))
137 
138 #endif /* _LP64 */
139 
140 
141 
142 /*
143  * switch between a node and data pointer for a given tree
144  * the value of "o" is tree->avl_offset
145  */
146 #define	AVL_NODE2DATA(n, o)	((void *)((uintptr_t)(n) - (o)))
147 #define	AVL_DATA2NODE(d, o)	((struct avl_node *)((uintptr_t)(d) + (o)))
148 
149 
150 
151 /*
152  * macros used to create/access an avl_index_t
153  */
154 #define	AVL_INDEX2NODE(x)	((avl_node_t *)((x) & ~1))
155 #define	AVL_INDEX2CHILD(x)	((x) & 1)
156 #define	AVL_MKINDEX(n, c)	((avl_index_t)(n) | (c))
157 
158 
159 /*
160  * The tree structure. The fields avl_root, avl_compar, and avl_offset come
161  * first since they are needed for avl_find().  We want them to fit into
162  * a single 64 byte cache line to make avl_find() as fast as possible.
163  */
164 struct avl_tree {
165 	struct avl_node *avl_root;	/* root node in tree */
166 	int (*avl_compar)(const void *, const void *);
167 	size_t avl_offset;		/* offsetof(type, avl_link_t field) */
168 	unsigned long avl_numnodes;	/* number of nodes in the tree */
169 	size_t avl_size;		/* sizeof user type struct */
170 };
171 
172 
173 /*
174  * This will only by used via AVL_NEXT() or AVL_PREV()
175  */
176 extern void *avl_walk(struct avl_tree *, void *, int);
177 
178 
179 /*
180  * The data structure nodes are anchored at an "avl_tree_t" (the equivalent
181  * of a list header) and the individual nodes will have a field of
182  * type "avl_node_t" (corresponding to list pointers).
183  *
184  * The type "avl_index_t" is used to indicate a position in the list for
185  * certain calls.
186  *
187  * The usage scenario is generally:
188  *
189  * 1. Create the list/tree with: avl_create()
190  *
191  * followed by any mixture of:
192  *
193  * 2a. Insert nodes with: avl_add(), or avl_find() and avl_insert()
194  *
195  * 2b. Visited elements with:
196  *	 avl_first() - returns the lowest valued node
197  *	 avl_last() - returns the highest valued node
198  *	 AVL_NEXT() - given a node go to next higher one
199  *	 AVL_PREV() - given a node go to previous lower one
200  *
201  * 2c.  Find the node with the closest value either less than or greater
202  *	than a given value with avl_nearest().
203  *
204  * 2d. Remove individual nodes from the list/tree with avl_remove().
205  *
206  * and finally when the list is being destroyed
207  *
208  * 3. Use avl_destroy_nodes() to quickly process/free up any remaining nodes.
209  *    Note that once you use avl_destroy_nodes(), you can no longer
210  *    use any routine except avl_destroy_nodes() and avl_destoy().
211  *
212  * 4. Use avl_destroy() to destroy the AVL tree itself.
213  *
214  * Any locking for multiple thread access is up to the user to provide, just
215  * as is needed for any linked list implementation.
216  */
217 
218 
219 /*
220  * Type used for the root of the AVL tree.
221  */
222 typedef struct avl_tree avl_tree_t;
223 
224 /*
225  * The data nodes in the AVL tree must have a field of this type.
226  */
227 typedef struct avl_node avl_node_t;
228 
229 /*
230  * An opaque type used to locate a position in the tree where a node
231  * would be inserted.
232  */
233 typedef uintptr_t avl_index_t;
234 
235 
236 /*
237  * Direction constants used for avl_nearest().
238  */
239 #define	AVL_BEFORE	(0)
240 #define	AVL_AFTER	(1)
241 
242 
243 /*
244  * Prototypes
245  *
246  * Where not otherwise mentioned, "void *" arguments are a pointer to the
247  * user data structure which must contain a field of type avl_node_t.
248  *
249  * Also assume the user data structures looks like:
250  *	stuct my_type {
251  *		...
252  *		avl_node_t	my_link;
253  *		...
254  *	};
255  */
256 
257 /*
258  * Initialize an AVL tree. Arguments are:
259  *
260  * tree   - the tree to be initialized
261  * compar - function to compare two nodes, it must return exactly: -1, 0, or +1
262  *          -1 for <, 0 for ==, and +1 for >
263  * size   - the value of sizeof(struct my_type)
264  * offset - the value of OFFSETOF(struct my_type, my_link)
265  */
266 extern void avl_create(avl_tree_t *tree,
267 	int (*compar) (const void *, const void *), size_t size, size_t offset);
268 
269 
270 /*
271  * Find a node with a matching value in the tree. Returns the matching node
272  * found. If not found, it returns NULL and then if "where" is not NULL it sets
273  * "where" for use with avl_insert() or avl_nearest().
274  *
275  * node   - node that has the value being looked for
276  * where  - position for use with avl_nearest() or avl_insert(), may be NULL
277  */
278 extern void *avl_find(avl_tree_t *tree, void *node, avl_index_t *where);
279 
280 /*
281  * Insert a node into the tree.
282  *
283  * node   - the node to insert
284  * where  - position as returned from avl_find()
285  */
286 extern void avl_insert(avl_tree_t *tree, void *node, avl_index_t where);
287 
288 /*
289  * Insert "new_data" in "tree" in the given "direction" either after
290  * or before the data "here".
291  *
292  * This might be usefull for avl clients caching recently accessed
293  * data to avoid doing avl_find() again for insertion.
294  *
295  * new_data	- new data to insert
296  * here		- existing node in "tree"
297  * direction	- either AVL_AFTER or AVL_BEFORE the data "here".
298  */
299 extern void avl_insert_here(avl_tree_t *tree, void *new_data, void *here,
300     int direction);
301 
302 
303 /*
304  * Return the first or last valued node in the tree. Will return NULL
305  * if the tree is empty.
306  *
307  */
308 extern void *avl_first(avl_tree_t *tree);
309 extern void *avl_last(avl_tree_t *tree);
310 
311 
312 /*
313  * Return the next or previous valued node in the tree.
314  * AVL_NEXT() will return NULL if at the last node.
315  * AVL_PREV() will return NULL if at the first node.
316  *
317  * node   - the node from which the next or previous node is found
318  */
319 #define	AVL_NEXT(tree, node)	avl_walk(tree, node, AVL_AFTER)
320 #define	AVL_PREV(tree, node)	avl_walk(tree, node, AVL_BEFORE)
321 
322 
323 /*
324  * Find the node with the nearest value either greater or less than
325  * the value from a previous avl_find(). Returns the node or NULL if
326  * there isn't a matching one.
327  *
328  * where     - position as returned from avl_find()
329  * direction - either AVL_BEFORE or AVL_AFTER
330  *
331  * EXAMPLE get the greatest node that is less than a given value:
332  *
333  *	avl_tree_t *tree;
334  *	struct my_data look_for_value = {....};
335  *	struct my_data *node;
336  *	struct my_data *less;
337  *	avl_index_t where;
338  *
339  *	node = avl_find(tree, &look_for_value, &where);
340  *	if (node != NULL)
341  *		less = AVL_PREV(tree, node);
342  *	else
343  *		less = avl_nearest(tree, where, AVL_BEFORE);
344  */
345 extern void *avl_nearest(avl_tree_t *tree, avl_index_t where, int direction);
346 
347 
348 /*
349  * Add a single node to the tree.
350  * The node must not be in the tree, and it must not
351  * compare equal to any other node already in the tree.
352  *
353  * node   - the node to add
354  */
355 extern void avl_add(avl_tree_t *tree, void *node);
356 
357 
358 /*
359  * Remove a single node from the tree.  The node must be in the tree.
360  *
361  * node   - the node to remove
362  */
363 extern void avl_remove(avl_tree_t *tree, void *node);
364 
365 /*
366  * Reinsert a node only if its order has changed relative to its nearest
367  * neighbors. To optimize performance avl_update_lt() checks only the previous
368  * node and avl_update_gt() checks only the next node. Use avl_update_lt() and
369  * avl_update_gt() only if you know the direction in which the order of the
370  * node may change.
371  */
372 extern boolean_t avl_update(avl_tree_t *, void *);
373 extern boolean_t avl_update_lt(avl_tree_t *, void *);
374 extern boolean_t avl_update_gt(avl_tree_t *, void *);
375 
376 /*
377  * Return the number of nodes in the tree
378  */
379 extern unsigned long avl_numnodes(avl_tree_t *tree);
380 
381 /*
382  * Return B_TRUE if there are zero nodes in the tree, B_FALSE otherwise.
383  */
384 extern boolean_t avl_is_empty(avl_tree_t *tree);
385 
386 /*
387  * Used to destroy any remaining nodes in a tree. The cookie argument should
388  * be initialized to NULL before the first call. Returns a node that has been
389  * removed from the tree and may be free()'d. Returns NULL when the tree is
390  * empty.
391  *
392  * Once you call avl_destroy_nodes(), you can only continuing calling it and
393  * finally avl_destroy(). No other AVL routines will be valid.
394  *
395  * cookie - a "void *" used to save state between calls to avl_destroy_nodes()
396  *
397  * EXAMPLE:
398  *	avl_tree_t *tree;
399  *	struct my_data *node;
400  *	void *cookie;
401  *
402  *	cookie = NULL;
403  *	while ((node = avl_destroy_nodes(tree, &cookie)) != NULL)
404  *		free(node);
405  *	avl_destroy(tree);
406  */
407 extern void *avl_destroy_nodes(avl_tree_t *tree, void **cookie);
408 
409 
410 /*
411  * Final destroy of an AVL tree. Arguments are:
412  *
413  * tree   - the empty tree to destroy
414  */
415 extern void avl_destroy(avl_tree_t *tree);
416 
417 
418 
419 #ifdef	__cplusplus
420 }
421 #endif
422 
423 #endif	/* FB_AVL_H */
424