xref: /openssl/doc/designs/thread-api.md (revision d55fc027)
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