From: Hugo Landau <hlandau@openssl.org>
Date: Wed, 30 Aug 2023 12:19:40 +0000 (+0100)
Subject: Document OSSL_get_thread_support_flags()
X-Git-Tag: openssl-3.2.0-alpha1~56
X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=cc50b44e555d71a10cdc45588d1b57523fb95ee4;p=thirdparty%2Fopenssl.git

Document OSSL_get_thread_support_flags()

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21905)
---

diff --git a/doc/man3/CRYPTO_THREAD_run_once.pod b/doc/man3/CRYPTO_THREAD_run_once.pod
index 1badd193978..b6ca5f1fafa 100644
--- a/doc/man3/CRYPTO_THREAD_run_once.pod
+++ b/doc/man3/CRYPTO_THREAD_run_once.pod
@@ -8,7 +8,8 @@ CRYPTO_THREAD_unlock, CRYPTO_THREAD_lock_free,
 CRYPTO_atomic_add, CRYPTO_atomic_or, CRYPTO_atomic_load,
 CRYPTO_atomic_load_int,
 OSSL_set_max_threads, OSSL_get_max_threads,
-OSSL_get_thread_support_flags - OpenSSL thread support
+OSSL_get_thread_support_flags, OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL,
+OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN - OpenSSL thread support
 
 =head1 SYNOPSIS
 
@@ -33,6 +34,9 @@ OSSL_get_thread_support_flags - OpenSSL thread support
  uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx);
  uint32_t OSSL_get_thread_support_flags(void);
 
+ #define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL
+ #define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN
+
 =head1 DESCRIPTION
 
 OpenSSL can be safely used in multi-threaded applications provided that
@@ -121,6 +125,17 @@ spawned unless (and until) there is demand. Thread polling is disabled by
 default. To enable threading you must call OSSL_set_max_threads() explicitly.
 Under no circumstances is this done for you.
 
+=item *
+
+OSSL_get_thread_support_flags() determines what thread pool functionality
+OpenSSL is compiled with and is able to support in the current run time
+environment. B<OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL> indicates that the base
+thread pool functionality is available, and
+B<OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN> indicates that the default thread pool
+model is available. The default thread pool model is currently the only model
+available, therefore both of these flags must be set for thread pool
+functionality to be used.
+
 =back
 
 =head1 RETURN VALUES
@@ -140,6 +155,9 @@ OSSL_get_max_threads() returns the maximum number of threads currently allowed
 to be used by the thread pool. If thread pooling is disabled or not available,
 returns 0.
 
+OSSL_get_thread_support_flags() returns zero or more B<OSSL_THREAD_SUPPORT_FLAG>
+values.
+
 The other functions return 1 on success, or 0 on error.
 
 =head1 NOTES
diff --git a/util/other.syms b/util/other.syms
index 4bac4afeaad..b65e4d97167 100644
--- a/util/other.syms
+++ b/util/other.syms
@@ -697,6 +697,8 @@ OSSL_TRACE_CANCEL                       define
 OSSL_TRACE1                             define
 OSSL_TRACE2                             define
 OSSL_TRACE9                             define
+OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL    define
+OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN  define
 TS_VERIFY_CTS_set_certs                 define deprecated 3.0.0
 EVP_PKEY_get1_tls_encodedpoint          define deprecated 3.0.0
 EVP_PKEY_set1_tls_encodedpoint          define deprecated 3.0.0