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