xref: /illumos-gate/usr/src/man/man3avl/avl_destroy_nodes.3avl (revision 1f5207b7604fb44407eb4342aff613f7c4508508)
1.\"
2.\" This file and its contents are supplied under the terms of the
3.\" Common Development and Distribution License ("CDDL"), version 1.0.
4.\" You may only use this file in accordance with the terms of version
5.\" 1.0 of the CDDL.
6.\"
7.\" A full copy of the text of the CDDL should have accompanied this
8.\" source.  A copy of the CDDL is also available via the Internet at
9.\" http://www.illumos.org/license/CDDL.
10.\"
11.\"
12.\" Copyright 2015 Joyent, Inc.
13.\"
14.Dd Dec 03, 2015
15.Dt AVL_DESTROY_NODES 3AVL
16.Os
17.Sh NAME
18.Nm avl_destroy_nodes
19.Nd efficiently remove nodes from an AVL tree
20.Sh SYNOPSIS
21.Lb libavl
22.In sys/avl.h
23.Ft void *
24.Fo avl_destroy_nodes
25.Fa "avl_tree_t *tree"
26.Fa "void **cookie"
27.Fc
28.Sh DESCRIPTION
29The
30.Fn avl_destroy_nodes
31function is used to efficiently remove nodes from the AVL tree rooted at
32.Fa tree .
33.Pp
34After the
35.Fn avl_destroy_nodes
36function is called on an AVL tree, the only valid functions that may be
37called on it are additional calls to
38.Fn avl_destroy_nodes
39and finally
40.Fn avl_destroy .
41.Pp
42Before calling
43.Fn avl_destroy_nodes ,
44callers must first initialize a value of type
45.Vt "void *"
46to
47.Sy NULL
48and pass a pointer to it as the argument
49.Fa cookie .
50This is an opaque value that will be used to maintain where to next
51delete items from the tree.
52Callers should never modify it after initializing it.
53After each call to
54.Fn avl_destroy_nodes ,
55.Fa cookie
56will be updated and must be passed to subsequent calls to
57.Fn avl_destroy_nodes .
58.Pp
59Each time
60.Fn avl_destroy_nodes
61is called, it will return a pointer to an object that had previously
62been inserted into the tree, allowing a caller the opportunity to delete
63or clean it up.
64Once
65.Fn avl_destroy_nodes
66returns a
67.Sy NULL
68pointer, then the tree is empty and the caller should proceed to call
69.Xr avl_destroy 3AVL .
70.Pp
71The examples in
72.Xr libavl 3LIB
73demonstrate the correct usage of this interface.
74.Sh RETURN VALUES
75The
76.Fn avl_destroy_nodes
77function will return a pointer to the object just removed from
78the tree rooted at
79.Fa tree
80and if
81.Fa tree
82is empty, it will return
83.Sy NULL .
84.Sh EXAMPLES
85See the
86.Sy EXAMPLES
87section in
88.Xr libavl 3LIB .
89.Sh INTERFACE STABILITY
90.Sy Committed
91.Sh MT-Level
92See
93.Sx Locking
94in
95.Xr libavl 3LIB .
96.Sh SEE ALSO
97.Xr avl_destroy 3AVL ,
98.Xr libavl 3LIB
99