1Thread Pool Support 2=================== 3 4OpenSSL wishes to support the internal use of threads for purposes of 5concurrency and parallelism in some circumstances. There are various reasons why 6this is desirable: 7 8 - Some algorithms are designed to be run in parallel (Argon2); 9 - Some transports (e.g. QUIC, DTLS) may need to handle timer events 10 independently of application calls to OpenSSL. 11 12To support this end, OpenSSL can manage an internal thread pool. Tasks can be 13scheduled on the internal thread pool. 14 15There is currently a single model available to an application which wants to use 16the thread pool functionality, known as the “default model”. More models 17providing more flexible or advanced usage may be added in future releases. 18 19A thread pool is managed on a per-`OSSL_LIB_CTX` basis. 20 21Default Model 22------------- 23 24In the default model, OpenSSL creates and manages threads up to a maximum 25number of threads authorized by the application. 26 27The application enables thread pooling by calling the following function 28during its initialisation: 29 30```c 31/* 32 * Set the maximum number of threads to be used by the thread pool. 33 * 34 * If the argument is 0, thread pooling is disabled. OpenSSL will not create any 35 * threads and existing threads in the thread pool will be torn down. 36 * 37 * Returns 1 on success and 0 on failure. Returns failure if OpenSSL-managed 38 * thread pooling is not supported (for example, if it is not supported on the 39 * current platform, or because OpenSSL is not built with the necessary 40 * support). 41 */ 42int OSSL_set_max_threads(OSSL_LIB_CTX *ctx, uint64_t max_threads); 43 44/* 45 * Get the maximum number of threads currently allowed to be used by the 46 * thread pool. If thread pooling is disabled or not available, returns 0. 47 */ 48uint64_t OSSL_get_max_threads(OSSL_LIB_CTX *ctx); 49``` 50 51The maximum thread count is a limit, not a target. Threads will not be spawned 52unless (and until) there is demand. 53 54As usual, `ctx` can be NULL to use the default library context. 55 56Capability Detection 57-------------------- 58 59These functions allow the caller to determine if OpenSSL was built with threads 60support. 61 62```c 63/* 64 * Retrieves flags indicating what threading functionality OpenSSL can support 65 * based on how it was built and the platform on which it was running. 66 */ 67/* Is thread pool functionality supported at all? */ 68#define OSSL_THREAD_SUPPORT_FLAG_THREAD_POOL (1U<<0) 69 70/* 71 * Is the default model supported? If THREAD_POOL is supported but DEFAULT_SPAWN 72 * is not supported, another model must be used. Note that there is currently 73 * only one supported model (the default model), but there may be more in the 74 * future. 75 */ 76#define OSSL_THREAD_SUPPORT_FLAG_DEFAULT_SPAWN (1U<<1) 77 78/* Returns zero or more of OSSL_THREAD_SUPPORT_FLAG_*. */ 79uint32_t OSSL_get_thread_support_flags(void); 80``` 81 82Build Options 83------------- 84 85A build option `thread-pool`/`no-thread-pool` will be introduced which allows 86thread pool functionality to be compiled out. `no-thread-pool` implies 87`no-default-thread-pool`. 88 89A build option `default-thread-pool`/`no-default-thread-pool` will be introduced 90which allows the default thread pool functionality to be compiled out. If this 91functionality is compiled out, another thread pool model must be used. Since the 92default model is the only currently supported model, disabling the default model 93renders threading functionality unusable. As such, there is little reason to use 94this option instead of `thread-pool/no-thread-pool`, however this option is 95nonetheless provided for symmetry when additional models are introduced in the 96future. 97 98Internals 99--------- 100 101New internal components will need to be introduced (e.g. condition variables) 102to support this functionality, however there is no intention of making 103this functionality public at this time. 104
