diff options
author | Hugo Landau <hlandau@openssl.org> | 2022-07-25 13:51:42 +0100 |
---|---|---|
committer | Tomas Mraz <tomas@openssl.org> | 2022-11-14 12:21:22 +0100 |
commit | d55fc027b9af85b1054cdbc017046a9070935086 (patch) | |
tree | dcea7819a76f44f9eff78fc07ecaf25efe76c60b /doc | |
parent | cbf965b4f3ba8567624767239aebe4d04c62558a (diff) |
Add thread pool design document (phase 1)
Reviewed-by: Paul Dale <pauli@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/19455)
Diffstat (limited to 'doc')
-rw-r--r-- | doc/designs/thread-api.md | 103 |
1 files changed, 103 insertions, 0 deletions
diff --git a/doc/designs/thread-api.md b/doc/designs/thread-api.md new file mode 100644 index 0000000000..c6ca5aac79 --- /dev/null +++ b/doc/designs/thread-api.md @@ -0,0 +1,103 @@ +Thread Pool Support +=================== + +OpenSSL wishes to support the internal use of threads for purposes of +concurrency and parallelism in some circumstances. There are various reasons why +this is desirable: + + - Some algorithms are designed to be run in parallel (Argon2); + - Some transports (e.g. QUIC, DTLS) may need to handle timer events + independently of application calls to OpenSSL. + +To support this end, OpenSSL can manage an internal thread pool. Tasks can be +scheduled on the internal thread pool. + +There is currently a single model available to an application which wants to use +the thread pool functionality, known as the “default model”. More models +providing more flexible or advanced usage may be added in future releases. + +A thread pool is managed on a per-`OSSL_LIB_CTX` basis. + +Default Model +------------- + +In the default model, OpenSSL creates and manages threads up to a maximum +number of threads authorized by the application. + +The application enables thread pooling by calling the following function +during its initialisation: + +```c +/* + * Set 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 down. + * + * Returns 1 on success and 0 on failure. Returns failure if OpenSSL-managed + * thread pooling is not supported (for example, if it is not supported on the + * current platform, or because OpenSSL is not built with the necessary + * support). + */ +int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads); + +/* + * Get the maximum number of threads currently allowed to be used by the + * thread pool. If thread pooling is disabled or not available, returns 0. + */ +uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx); +``` + +The maximum thread count is a limit, not a target. Threads will not be spawned +unless (and until) there is demand. + +As usual, `ctx` can be NULL to use the default library context. + +Capability Detection +-------------------- + +These functions allow the caller to determine if OpenSSL was built with threads +support. + +```c +/* + * Retrieves flags indicating what threading functionality OpenSSL can support + * based on how it was built and the platform on which it was running. + */ +/* Is thread pool functionality supported at all? */ +#define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL (1U<<0) + +/* + * Is the default model supported? If THREAD_POOL is supported but DEFAULT_SPAWN + * is not supported, another model must be used. Note that there is currently + * only one supported model (the default model), but there may be more in the + * future. + */ +#define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN (1U<<1) + +/* Returns zero or more of OSSL_THREAD_SUPPORT_FLAG_*. */ +uint32_t OSSL_get_thread_support_flags(void); +``` + +Build Options +------------- + +A build option `thread-pool`/`no-thread-pool` will be introduced which allows +thread pool functionality to be compiled out. `no-thread-pool` implies +`no-default-thread-pool`. + +A build option `default-thread-pool`/`no-default-thread-pool` will be introduced +which allows the default thread pool functionality to be compiled out. If this +functionality is compiled out, another thread pool model must be used. Since the +default model is the only currently supported model, disabling the default model +renders threading functionality unusable. As such, there is little reason to use +this option instead of `thread-pool/no-thread-pool`, however this option is +nonetheless provided for symmetry when additional models are introduced in the +future. + +Internals +--------- + +New internal components will need to be introduced (e.g. condition variables) +to support this functionality, however there is no intention of making +this functionality public at this time. |