svn commit: r257921 - head/share/man/man3

[Bruce M Simpson]

Author: bms
Date: Sun Nov 10 19:41:04 2013
New Revision: 257921
URL: http://svnweb.freebsd.org/changeset/base/257921

Log:
  Document the RB_FOREACH_FROM() and RB_FOREACH_REVERSE_FROM() macros.
  
  These are largely syntactic sugar. However, they improve code
  readability where an RB_FOREACH() or RB_FOREACH_REVERSE()
  traversal has been interrupted and must be resumed. Performance
  is improved by avoiding unnecessary traversal from the head node.

Modified:
  head/share/man/man3/tree.3

Modified: head/share/man/man3/tree.3
==============================================================================
--- head/share/man/man3/tree.3	Sun Nov 10 18:46:59 2013	(r257920)
+++ head/share/man/man3/tree.3	Sun Nov 10 19:41:04 2013	(r257921)
@@ -30,7 +30,7 @@
 .\"
 .\" $FreeBSD$
 .\"
-.Dd November 4, 2013
+.Dd November 10, 2013
 .Dt TREE 3
 .Os
 .Sh NAME
@@ -70,8 +70,10 @@
 .Nm RB_RIGHT ,
 .Nm RB_PARENT ,
 .Nm RB_FOREACH ,
+.Nm RB_FOREACH_FROM ,
 .Nm RB_FOREACH_SAFE ,
 .Nm RB_FOREACH_REVERSE ,
+.Nm RB_FOREACH_REVERSE_FROM ,
 .Nm RB_FOREACH_REVERSE_SAFE ,
 .Nm RB_INIT ,
 .Nm RB_INSERT ,
@@ -137,8 +139,10 @@
 .Ft "struct TYPE *"
 .Fn RB_PARENT "struct TYPE *elm" "RB_ENTRY NAME"
 .Fn RB_FOREACH VARNAME NAME "RB_HEAD *head"
+.Fn RB_FOREACH_FROM "VARNAME" "NAME" "RB_HEAD *head" "POS_VARNAME"
 .Fn RB_FOREACH_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME"
 .Fn RB_FOREACH_REVERSE VARNAME NAME "RB_HEAD *head"
+.Fn RB_FOREACH_REVERSE_FROM "VARNAME" "NAME" "RB_HEAD *head" "POS_VARNAME"
 .Fn RB_FOREACH_REVERSE_SAFE "VARNAME" "NAME" "RB_HEAD *head" "TEMP_VARNAME"
 .Ft void
 .Fn RB_INIT "RB_HEAD *head"
@@ -470,6 +474,15 @@ they permit both the removal of np
 as well as freeing it from within the loop safely
 without interfering with the traversal.
 .Pp
+Both
+.Fn RB_FOREACH_FROM
+and
+.Fn RB_FOREACH_REVERSE_FROM
+may be used to continue an interrupted traversal
+in a forward or reverse direction respectively.
+The resume point should be passed as their last argument,
+and will be overwritten to provide safe traversal.
+.Pp
 The
 .Fn RB_EMPTY
 macro should be used to check whether a red-black tree is empty.