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