usr/src/man/man3avl/avl_destroy_nodes.3avl

   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
  29 The
  30 .Fn avl_destroy_nodes
  31 function is used to efficiently remove nodes from the AVL tree rooted at
  32 .Fa tree .
  33 .Pp
  34 After the
  35 .Fn avl_destroy_nodes
  36 function is called on an AVL tree, the only valid functions that may be
  37 called on it are additional calls to
  38 .Fn avl_destroy_nodes
  39 and finally
  40 .Fn avl_destroy .
  41 .Pp
  42 Before calling
  43 .Fn avl_destroy_nodes ,
  44 callers must first initialize a value of type
  45 .Vt "void *"
  46 to
  47 .Sy NULL
  48 and pass a pointer to it as the argument
  49 .Fa cookie .
  50 This is an opaque value that will be used to maintain where to next
  51 delete items from the tree. Callers should never modify it after
  52 initializing it. After each call to
  53 .Fn avl_destroy_nodes ,
  54 .Fa cookie
  55 will be updated and must be passed to subsequent calls to
  56 .Fn avl_destroy_nodes.
  57 .Pp
  58 Each time
  59 .Fn avl_destroy_nodes
  60 is called, it will return a pointer to an object that had previously
  61 been inserted into the tree, allowing a caller the opportunity to delete
  62 or clean it up. Once
  63 .Fn avl_destroy_nodes
  64 returns a
  65 .Sy NULL
  66 pointer, then the tree is empty and the caller should proceed to call
  67 .Xr avl_destroy 3AVL .
  68 .Pp
  69 The examples in
  70 .Xr libavl 3LIB
  71 demonstrate the correct usage of this interface.
  72 .Sh RETURN VALUES
  73 The
  74 .Fn avl_destroy_nodes
  75 function will return a pointer to the object just removed from
  76 the tree rooted at
  77 .Fa tree
  78 and if
  79 .Fa tree
  80 is empty, it will return
  81 .Sy NULL .
  82 .Sh EXAMPLES
  83 See the
  84 .Sy EXAMPLES
  85 section in
  86 .Xr libavl 3LIB .
  87 .Sh INTERFACE STABILITY
  88 .Sy Committed
  89 .Sh MT-Level
  90 See
  91 .Sx Locking
  92 in
  93 .Xr libavl 3LIB .
  94 .Sh SEE ALSO
  95 .Xr avl_destroy 3AVL ,
  96 .Xr libavl 3LIB