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 May 07, 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. Callers should never modify it after 52initializing it. After each call to 53.Fn avl_destroy_nodes , 54.Fa cookie 55will be updated and must be passed to subsequent calls to 56.Fn avl_destroy_nodes. 57.Pp 58Each time 59.Fn avl_destroy_nodes 60is called, it will return a pointer to an object that had previously 61been inserted into the tree, allowing a caller the opportunity to delete 62or clean it up. Once 63.Fn avl_destroy_nodes 64returns a 65.Sy NULL 66pointer, then the tree is empty and the caller should proceed to call 67.Xr avl_destroy 3AVL . 68.Pp 69The examples in 70.Xr libavl 3LIB 71demonstrate the correct usage of this interface. 72.Sh RETURN VALUES 73The 74.Fn avl_destroy_nodes 75function will return a pointer to the object just removed from 76the tree rooted at 77.Fa tree 78and if 79.Fa tree 80is empty, it will return 81.Sy NULL . 82.Sh EXAMPLES 83See the 84.Sy EXAMPLES 85section in 86.Xr libavl 3LIB . 87.Sh INTERFACE STABILITY 88.Sy Committed 89.Sh MT-Level 90See 91.Sx Locking 92in 93.Xr libavl 3LIB . 94.Sh SEE ALSO 95.Xr libavl 3LIB , 96.Xr avl_destroy 3AVL 97