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