From: Neil Horman <nhorman@openssl.org>
Date: Thu, 2 Apr 2026 19:24:27 +0000 (-0400)
Subject: Add docs for new atomic apis
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=bdfac7bb669f02f441664b5f439c282f7d27569b;p=thirdparty%2Fopenssl.git

Add docs for new atomic apis

Documents CRYPTO_atomic_load_ptr(), CRYPTO_atomic_store_ptr() and
CRYPTO_atomic_cmp_exch_ptr()

Reviewed-by: Paul Dale <paul.dale@oracle.com>
Reviewed-by: Nikola Pajkovsky <nikolap@openssl.org>
MergeDate: Tue Apr 14 08:29:33 2026
(Merged from https://github.com/openssl/openssl/pull/30670)
---

diff --git a/CHANGES.md b/CHANGES.md
index ca66469586..2b55f6ebdf 100644
--- a/CHANGES.md
+++ b/CHANGES.md
@@ -42,6 +42,11 @@ OpenSSL Releases
 
    *Shane Lontis*
 
+ * The API functions `CRYPTO_atomic_load_ptr`, `CRYPTO_atomic_store_ptr`, and
+   `CRYPTO_atomic_cmp_exch_ptr` have been added to libcrypto.
+
+   *Neil Horman*
+
  * The `openssl pkeyutl` command now uses memory-mapped I/O when reading
    raw input from a file for oneshot sign/verify operations (such as Ed25519,
    Ed448, and ML-DSA) on platforms that support it (Unix-like). The
diff --git a/NEWS.md b/NEWS.md
index 4829d57c47..7abd5c5f65 100644
--- a/NEWS.md
+++ b/NEWS.md
@@ -27,7 +27,8 @@ OpenSSL 4.0
 
 ### Major changes between OpenSSL 4.0 and OpenSSL 4.1 [under development]
 
-  * none
+  * API calls `CRYPTO_atomic_load_ptr`, `CRYPTO_atomic_store_ptr`, and
+    `CRYPTO_atomic_cmp_exch_ptr` have been added.
 
 ### Major changes between OpenSSL 3.6 and OpenSSL 4.0 [under development]
 
diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod
index 51671646f7..161105471a 100644
--- a/doc/man3/CRYPTO_THREAD_run_once.pod
+++ b/doc/man3/CRYPTO_THREAD_run_once.pod
@@ -7,7 +7,8 @@ CRYPTO_THREAD_lock_new, CRYPTO_THREAD_read_lock, CRYPTO_THREAD_write_lock,
 CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free,
 CRYPTO_atomic_add, CRYPTO_atomic_add64, CRYPTO_atomic_and, CRYPTO_atomic_or,
 CRYPTO_atomic_load, CRYPTO_atomic_store, CRYPTO_atomic_load_int,
-CRYPTO_atomic_store_int,
+CRYPTO_atomic_store_int, CRYPTO_atomic_load_ptr, CRYPTO_atomic_store_ptr,
+CRYPTO_atomic_cmp_exch_ptr,
 OSSL_set_max_threads, OSSL_get_max_threads,
 OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL,
 OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support
@@ -36,6 +37,9 @@ OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support
  int CRYPTO_atomic_store(uint64_t *dst, uint64_t val, CRYPTO_RWLOCK *lock);
  int CRYPTO_atomic_load_int(int *val, int *ret, CRYPTO_RWLOCK *lock);
  int CRYPTO_atomic_store_int(int *dst, int val, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_load_ptr(void **ptr, void **ret, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_store_ptr(void **dst, void **val, CRYPTO_RWLOCK *lock);
+ int CRYPTO_atomic_cmp_exch_ptr(void **ptr, void **expect, void *desire, CRYPTO_RWLOCK *lock);
 
  int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads);
  uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);
@@ -155,6 +159,34 @@ operates on an I<int> value instead of a I<uint64_t> value.
 
 =item *
 
+int CRYPTO_atomic_load_ptr(void **ptr, void **ret, CRYPTO_RWLOCK *lock);
+
+CRYPTO_atomic_load_ptr() atomically loads the void * contents of I<*ptr> to the contents of I<*ret>.
+I<lock> will be used to emulate atomic operations on platforms that do not support
+atomic operations.
+
+=item *
+
+int CRYPTO_atomic_store_ptr(void **dst, void **val, CRYPTO_RWLOCK *lock);
+
+CRYPTO_atomic_store_ptr() atomically stores the contents of I<*val> to the location pointed
+to by I<*p>.
+I<lock> will be used to emulate atomic operations on platforms that do not support
+atomic operations.
+
+=item *
+
+int CRYPTO_atomic_cmp_exch_ptr(void **ptr, void **expect, void *desire, CRYPTO_RWLOCK *lock);
+
+CRYPTO_atomic_cmp_exch_ptr() atomically performs a read-modify-write operation.  If the contents of
+I<*ptr> matches the contents of I<*expect> then the value of I<desire> is stored in I<*ptr> and the
+function returns 1.  If I<*ptr> does not match the contents of I<*expect>, then the contents of
+I<*ptr> are atomically loaded to the contents of I<*expect> and the function returns 0.
+I<lock> will be used to emulate atomic operations on platforms that do not support
+atomic operations.
+
+=item *
+
 OSSL_set_max_threads() sets the maximum number of threads to be used by the
 thread pool. If the argument is 0, thread pooling is disabled. OpenSSL will
 not create any threads and existing threads in the thread pool will be torn
@@ -282,6 +314,9 @@ were added in OpenSSL 3.4.
 
 CRYPTO_atomic_store_int() was added in OpenSSL 4.0.
 
+CRYPTO_atomic_load_ptr(), CRYPTO_atomic_store_ptr(), CRYPTO_atomic_cmp_exch_ptr()
+were added in OpenSSL 4.1
+
 =head1 COPYRIGHT
 
 Copyright 2000-2026 The OpenSSL Project Authors. All Rights Reserved.