doc: note that the stack find functions no longer modify the stack

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Todd Short <todd.short@me.com>
(Merged from https://github.com/openssl/openssl/pull/20842)

diff --git a/doc/man3/DEFINE_STACK_OF.pod b/doc/man3/DEFINE_STACK_OF.pod
index 12f033d977e0464b70673516b9d453ea1fef99fb..044228129baa7219b0882eb83a98875a27cf0008 100644 (file)
--- a/doc/man3/DEFINE_STACK_OF.pod
+++ b/doc/man3/DEFINE_STACK_OF.pod
@@ -178,10 +178,7 @@ where a comparison function has been specified, I<sk> is sorted and
 B<sk_I<TYPE>_find>() returns the index of a matching element or B<-1> if there
 is no match. Note that, in this case the comparison function will usually
 compare the values pointed to rather than the pointers themselves and
-the order of elements in I<sk> can change. Note that because the stack may be
-sorted as the result of a B<sk_I<TYPE>_find>() call, if a lock is being used to
-synchronise access to the stack across multiple threads, then that lock must be
-a "write" lock.
+the order of elements in I<sk> can change.
 
 B<sk_I<TYPE>_find_ex>() operates like B<sk_I<TYPE>_find>() except when a
 comparison function has been specified and no matching element is found.
@@ -295,6 +292,11 @@ and was not a public API.
 B<sk_I<TYPE>_reserve>() and B<sk_I<TYPE>_new_reserve>() were added in OpenSSL
 1.1.1.
 
+From OpenSSL 3.2.0, the B<sk_I<TYPE>_find>(), B<sk_I<TYPE>_find_ex>()
+and B<sk_I<TYPE>_find_all>() calls are read-only and do not sort the
+stack.  To avoid any performance implications this change introduces,
+B<sk_I<TYPE>_sort>() should be called before these find operations.
+
 =head1 COPYRIGHT
 
 Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved.