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