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