From: Matt Caswell <matt@openssl.org>
Date: Thu, 10 Dec 2020 16:57:33 +0000 (+0000)
Subject: Document the core_thread_start upcall
X-Git-Tag: openssl-3.0.0-alpha11~99
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=886ad0045bf128795049b48f7d7977f72cc7220c;p=thirdparty%2Fopenssl.git

Document the core_thread_start upcall

The core_thread_start upcall previously had a placeholder in the docs.

Reviewed-by: Tomas Mraz <tmraz@fedoraproject.org>
(Merged from https://github.com/openssl/openssl/pull/13660)
---

diff --git a/doc/man7/provider-base.pod b/doc/man7/provider-base.pod
index 7e8f5188a55..e2315e7bc4f 100644
--- a/doc/man7/provider-base.pod
+++ b/doc/man7/provider-base.pod
@@ -18,8 +18,11 @@ provider-base
  /* Functions offered by libcrypto to the providers */
  const OSSL_ITEM *core_gettable_params(const OSSL_CORE_HANDLE *handle);
  int core_get_params(const OSSL_CORE_HANDLE *handle, OSSL_PARAM params[]);
+
+ typedef void (*OSSL_thread_stop_handler_fn)(void *arg);
  int core_thread_start(const OSSL_CORE_HANDLE *handle,
                        OSSL_thread_stop_handler_fn handfn);
+
  OPENSSL_CORE_CTX *core_get_libctx(const OSSL_CORE_HANDLE *handle);
  void core_new_error(const OSSL_CORE_HANDLE *handle);
  void core_set_error_debug(const OSSL_CORE_HANDLE *handle,
@@ -164,7 +167,13 @@ core_get_params() retrieves parameters from the core for the given I<handle>.
 See L</Core parameters> below for a description of currently known
 parameters.
 
-=for comment core_thread_start() TBA
+The core_thread_start() function informs the core that the provider has started
+an interest in the current thread. The core will inform the provider when the
+thread eventually stops. It must be passed the I<handle> for this provider, as
+well as a callback I<handfn> which will be called when the thread stops. The
+callback will subsequently be called from the thread that is stopping and gets
+passed the provider context as an argument. This may be useful to perform thread
+specific clean up such as freeing thread local variables.
 
 core_get_libctx() retrieves the library context in which the library
 object for the current provider is stored, accessible through the I<handle>.