16424 libavl should expose avl_update{,_lt,_gt}

Reviewed by: Bill Sommerfeld <sommerfeld@hamachi.org>
Reviewed by: Toomas Soome <tsoome@me.com>
Approved by: Dan McDonald <danmcd@mnx.io>

usr/src/lib/libavl/mapfile-vers

@@ -39,6 +39,13 @@
 
 $mapfile_version 2
 
+SYMBOL_VERSION ILLUMOS_1.1 {
+    global:
+	avl_update;
+	avl_update_gt;
+	avl_update_lt;
+} ILLUMOS_1.0;
+
 SYMBOL_VERSION ILLUMOS_1.0 {
     global:
 	avl_add;

usr/src/man/man3avl/Makefile

@@ -28,14 +28,17 @@ MANFILES =					\
 		avl_is_empty.3avl		\
 		avl_nearest.3avl		\
 		avl_numnodes.3avl		\
-		avl_swap.3avl
+		avl_swap.3avl			\
+		avl_update.3avl
 
 MANLINKS =				\
 		AVL_NEXT.3avl		\
 		AVL_PREV.3avl		\
 		avl_insert_here.3avl	\
 		avl_last.3avl		\
-		avl_remove.3avl
+		avl_remove.3avl		\
+		avl_update_gt.3avl	\
+		avl_update_lt.3avl
 
 # avl_add.3avl
 avl_remove.3avl		:= LINKSRC = avl_add.3avl
@@ -48,6 +51,10 @@ avl_last.3avl		:= LINKSRC = avl_first.3avl
 # avl_insert.3avl
 avl_insert_here.3avl	:= LINKSRC = avl_insert.3avl
 
+# avl_update.3avl
+avl_update_gt.3avl	:= LINKSRC = avl_update.3avl
+avl_update_lt.3avl	:= LINKSRC = avl_update.3avl
+
 .KEEP_STATE:
 
 include		$(SRC)/man/Makefile.man

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

@@ -0,0 +1,83 @@
+.\"
+.\" This file and its contents are supplied under the terms of the
+.\" Common Development and Distribution License ("CDDL"), version 1.0.
+.\" You may only use this file in accordance with the terms of version
+.\" 1.0 of the CDDL.
+.\"
+.\" A full copy of the text of the CDDL should have accompanied this
+.\" source.  A copy of the CDDL is also available via the Internet at
+.\" http://www.illumos.org/license/CDDL.
+.\"
+.\"
+.\" Copyright 2024 Oxide Computer Company
+.\"
+.Dd Jan 27, 2024
+.Dt AVL_UPDATE 3AVL
+.Os
+.Sh NAME
+.Nm avl_update ,
+.Nm avl_update_gt ,
+.Nm avl_update_lt
+.Nd reinsert a node if its order has changed
+.Sh SYNOPSIS
+.Lb libavl
+.In sys/avl.h
+.Ft boolean_t
+.Fo avl_update
+.Fa "avl_tree_t *tree"
+.Fa "void *node"
+.Fc
+.Ft boolean_t
+.Fo avl_update_gt
+.Fa "avl_tree_t *tree"
+.Fa "void *node"
+.Fc
+.Ft boolean_t
+.Fo avl_update_lt
+.Fa "avl_tree_t *tree"
+.Fa "void *node"
+.Fc
+.Sh DESCRIPTION
+The
+.Fn avl_update
+function re-inserts
+.Fa node
+into
+.Fa tree
+only if its order has changed relative to its nearest neighbors.
+To optimize performance,
+.Fn avl_update_lt
+checks only the previous node and
+.Fn avl_update_gt
+checks only the next node.
+Use
+.Fn avl_update_lt
+and
+.Fn avl_update_gt
+only if you know the direction in which the order of the node may change.
+.Sh RETURN VALUES
+The
+.Fn avl_update ,
+.Fn avl_update_lt
+and
+.Fn avl_update_gt
+functions return
+.Sy B_TRUE
+if it was necessary to relocate the node due its order having changed
+relative to its nearest neighbors and
+.Sy B_FALSE
+otherwise.
+.Sh EXAMPLES
+See the
+.Sy EXAMPLES
+section in
+.Xr libavl 3LIB .
+.Sh INTERFACE STABILITY
+.Sy Committed
+.Sh MT-Level
+See
+.Sx Locking
+in
+.Xr libavl 3LIB .
+.Sh SEE ALSO
+.Xr libavl 3LIB

usr/src/man/man3lib/libavl.3lib

@@ -10,8 +10,9 @@
 .\"
 .\"
 .\" Copyright 2015 Joyent, Inc.
+.\" Copyright 2024 Oxide Computer Company
 .\"
-.Dd December 2, 2023
+.Dd January 27, 2024
 .Dt LIBAVL 3LIB
 .Os
 .Sh NAME
@@ -128,6 +129,8 @@ Individual functions are documented in their own manual pages.
 .It Sy avl_is_empty Ta Sy avl_last
 .It Sy avl_nearest Ta Sy avl_numnodes
 .It Sy avl_remove Ta Sy avl_swap
+.It Sy avl_update Ta Sy avl_update_gt
+.It Sy avl_update_lt Ta
 .El
 .Pp
 In addition, the library defines C pre-processor macros which are
@@ -205,6 +208,7 @@ $ gcc -Wall -o avl avl.c -lavl
  */
 
 #include <sys/avl.h>
+#include <assert.h>
 #include <stddef.h>
 #include <stdlib.h>
 #include <stdio.h>
@@ -383,6 +387,19 @@ swap_avl(void)
 	inttree_inspect();
 }
 
+static void
+update_avl(void)
+{
+	intnode_t lookup, *inp;
+	avl_index_t where;
+
+	lookup.in_val = 9;
+	inp = avl_find(&inttree, &lookup, &where);
+	assert(inp != NULL);
+	inp->in_val = 25;
+	avl_update(&inttree, inp);
+}
+
 /*
  * Remove all remaining nodes in the tree. We first use
  * avl_destroy_nodes to empty the tree, then avl_destroy to finish.
@@ -415,6 +432,7 @@ main(void)
 	insert_avl();
 	inttree_inspect();
 	swap_avl();
+	update_avl();
 	cleanup();
 	return (0);
 }
@@ -442,6 +460,9 @@ See
 .Xr avl_numnodes 3AVL ,
 .Xr avl_remove 3AVL ,
 .Xr avl_swap 3AVL ,
+.Xr avl_update 3AVL ,
+.Xr avl_update_gt 3AVL ,
+.Xr avl_update_lt 3AVL
 .Rs
 .%A Adel'son-Vel'skiy, G. M.
 .%A Landis, Ye. M.

usr/src/man/man9f/avl.9f

@@ -10,8 +10,9 @@
 .\"
 .\"
 .\" Copyright 2016 Joyent, Inc.
+.\" Copyright 2024 Oxide Computer Company
 .\"
-.Dd Mar 13, 2016
+.Dd Feb 27, 2024
 .Dt AVL 9F
 .Os
 .Sh NAME
@@ -30,26 +31,29 @@
 .Nm avl_numnodes ,
 .Nm avl_remove ,
 .Nm avl_swap ,
+.Nm avl_update ,
+.Nm avl_update_gt ,
+.Nm avl_update_lt ,
 .Nm AVL_NEXT ,
 .Nm AVL_PREV
 .Nd AVL tree routines
 .Sh DESCRIPTION
 AVL trees are a general purpose, self-balancing binary tree that can be
-used instead of the standard linked list interfaces --
+used instead of the standard linked list interfaces \(em
 .Xr list_create 9F .
 AVL trees are particularly useful either when order is important or
 better lookup performance is required.
 .Pp
 The AVL tree interfaces are identical in both userland and the kernel.
 For more general information on AVL trees, see
 .Xr libavl 3LIB .
-For more information on any of the funtions defined here, please see the
+For more information on any of the functions defined here, please see the
 corresponding manual page in section 3AVL.
 Please note, that while the descriptions in those manual pages are accurate for
 writers of Device Drivers, the examples provided use scaffolding not available
 in the kernel, such as the use of
 .Fn malloc ,
-and need to be adapated.
+and need to be adapted.
 .Sh CONTEXT
 All of the AVL routines may be used in user, kernel, and interrupt
 context.
@@ -85,6 +89,9 @@ for more information on synchronization primitives.
 .Xr AVL_PREV 3AVL ,
 .Xr avl_remove 3AVL ,
 .Xr avl_swap 3AVL ,
+.Xr avl_update 3AVL ,
+.Xr avl_update_gt 3AVL ,
+.Xr avl_update_lt 3AVL ,
 .Xr libavl 3LIB
 .Rs
 .%T Writing Device Drivers

usr/src/pkg/manifests/system-library.man3avl.inc

@@ -11,6 +11,7 @@
 
 #
 # Copyright 2015, Joyent, Inc.
+# Copyright 2024 Oxide Computer Company
 #
 
 link path=usr/share/man/man3avl/AVL_NEXT.3avl target=avl_first.3avl
@@ -29,4 +30,7 @@ file path=usr/share/man/man3avl/avl_nearest.3avl
 file path=usr/share/man/man3avl/avl_numnodes.3avl
 link path=usr/share/man/man3avl/avl_remove.3avl target=avl_add.3avl
 file path=usr/share/man/man3avl/avl_swap.3avl
+file path=usr/share/man/man3avl/avl_update.3avl
+link path=usr/share/man/man3avl/avl_update_gt.3avl target=avl_update.3avl
+link path=usr/share/man/man3avl/avl_update_lt.3avl target=avl_update.3avl