Fix typo in CONTRIBUTING.md

[thirdparty/openssl.git] / doc / designs / thread-api.md

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.