openssl-quic-concurrency.7ossl - Man Page

A QUIC domain is a group of QUIC resources such as listeners (see SSL_new_listener(3)) and connections which share common event processing resources, such as internal pollers, timers and locks. All usage of OpenSSL QUIC happens inside a QUIC domain.

These resources can be accessed and used concurrently depending on the circumstances. This man page discusses the available concurrency models and how they can be used.

A QUIC domain is instantiated either explicitly (SSL_new_domain(3)) or implicitly by calling SSL_new(3) or SSL_new_listener(3):

• An explicit QUIC domain is created by and visible to the application as a QUIC domain SSL object and has other QUIC SSL objects created underneath it, such as listeners or connections.
• An implicit QUIC domain is one which is created internally due to the direct creation of a QUIC connection or listener SSL object; the application does not explicitly create a QUIC domain SSL object and never directly references the domain.

Explicit creation of a QUIC domain provides the greatest level of control for an application. Applications can use an implicit QUIC domain for ease of use and to avoid needing to create a separate QUIC domain SSL object.

Regardless of whether a QUIC domain is explicitly created, the internal processing model is the same and the application must choose an appropriate concurrency model as discussed below.

The OpenSSL QUIC implementation supports multiple concurrency models to support a wide variety of usage scenarios.

The available concurrency models are as follows:

• The Single-Threaded Concurrency Model (SCM), which supports only application-synchronised single-threaded usage.
• The Contentive Concurrency Model (CCM), which supports multi-threaded usage.
• The Thread-Assisted Concurrency Model (TACM), which also supports multi-threaded usage and provides assistance to an application for handling QUIC timer events.

The merits of these models are as follows:

• The Single-Threaded Concurrency Model (SCM) performs no locking or synchronisation. It is entirely up to the application to synchronise access to the QUIC domain and its subsidiary SSL objects.

  This concurrency model is also useful for an application which wants to use the OpenSSL QUIC implementation as a pure state machine.

• The Contentive Concurrency Model (CCM) performs automatic locking when making API calls to SSL objects in a QUIC domain. This provides automatic synchronisation for multi-threaded usage of QUIC objects. For example, different QUIC stream SSL objects in the same QUIC connection can be safely accessed from different threads.

  This concurrency model adds the overhead of locking over the Single-Threaded Concurrency Model in order to support multi-threaded usage, but provides limited performance in highly contended multi-threaded usage due to its simple approach. However, it may still prove a good solution for a broad class of applications which spend the majority of their time in application logic and not in QUIC I/O processing.

  An advantage of this model relative to the more sophisticated concurrency models below is that it does not create any OS threads.

• The Thread-Assisted Concurrency Model (TACM) is identical to the Contentive Concurrency Model except that a thread is spun up in the background to ensure that QUIC timer events are handled in a timely fashion. This ensures that QUIC timeout events are handled even if an application does not periodically call into the QUIC domain to ensure that any outstanding QUIC-related timer or network I/O events are handled. The assist thread contends for the same resources like any other thread. However, handshake layer events (TLS) are never processed by the assist thread.

The default concurrency model is CCM or TACM, depending on the SSL_METHOD used with a SSL_CTX. Using OSSL_QUIC_client_method(3) results in a default concurrency model of CCM, whereas using OSSL_QUIC_client_thread_method(3) results in a default concurrency model of TACM.

Additional concurrency models may be offered in future releases of OpenSSL.

All of the supported concurrency models are capable of supporting blocking I/O calls, where application-level I/O calls (for example, to SSL_read_ex(3) or SSL_write_ex(3) on a QUIC stream SSL object) block until the request can be serviced. This includes the use of SSL_poll(3) in a blocking fashion.

Supporting blocking API calls reliably with multi-threaded usage requires the creation of additional OS resources such as internal file descriptors to allow threads to be woken when necessary. This creation of internal OS resources is optional and may need to be explicitly requested by an application depending on the chosen concurrency model. If this functionality is disabled, depending on the chosen concurrency model, blocking API calls may not be available and calls to SSL_set_blocking_mode(3) attempting to enable blocking mode may fail, notwithstanding the following section.

New applications are advised to choose a concurrency model as follows:

• A purely single-threaded application, or an application which wishes to use OpenSSL QUIC as a state machine and manage synchronisation itself, should explicitly select the SCM concurrency model.

• An application which wants to engage in multi-threaded usage of different QUIC connections or streams in the same QUIC domain should a) select the CCM or TACM concurrency model and b) explicitly opt in or out of blocking I/O support (depending on whether the application wishes to make blocking I/O calls), disabling Legacy Blocking Compatibility Mode.

  An application should select the CCM concurrency model if the application can guarantee that a QUIC domain will be serviced regularly (for example, because the application can guarantee that the timeout returned by SSL_get_event_timeout(3) will be handled). If an application is unable to do this, it should select the TACM concurrency model.

• Applications should explicitly configure a concurrency model during initialisation.

If using an explicit QUIC domain, a concurrency model is chosen when calling SSL_new_domain(3) by specifying zero or more of the following flags:

SSL_DOMAIN_FLAG_SINGLE_THREAD

Specifying this flag configures the Single-Threaded Concurrency Model (SCM).

SSL_DOMAIN_FLAG_MULTI_THREAD

Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless SSL_DOMAIN_FLAG_THREAD_ASSISTED is also specified).

SSL_DOMAIN_FLAG_THREAD_ASSISTED

Specifying this flag configures the Thread-Assisted Concurrency Model (TACM). It implies SSL_DOMAIN_FLAG_MULTI_THREAD.

SSL_DOMAIN_FLAG_BLOCKING

Enable reliable support for blocking I/O calls, allocating whatever OS resources are necessary to realise this. If this flag is specified, SSL_DOMAIN_FLAG_LEGACY_BLOCKING is ignored.

Details on the allocated OS resources can be found under "Consumption of OS Resources" below.

SSL_DOMAIN_FLAG_LEGACY_BLOCKING

Enables legacy blocking compatibility mode. See "Legacy Blocking Support Compatibility".

Mutually exclusive flag combinations result in an error (for example, combining SSL_DOMAIN_FLAG_SINGLE_THREAD and SSL_DOMAIN_FLAG_MULTI_THREADED).

The concurrency model for a domain cannot be changed after the domain is created.

If full blocking I/O support is selected using SSL_DOMAIN_FLAG_BLOCKING, at least one socket, socket-like OS handle or file descriptor must be allocated to allow one thread to wake other threads which may be blocking in calls to OS socket polling interfaces such as select(2) or poll(2). This is allocated automatically internally by OpenSSL.

If the Thread-Assisted Concurrency Model (TACM) is selected, a background thread is spawned. This also implies SSL_DOMAIN_FLAG_BLOCKING and the above.

The internal consumption by OpenSSL of mutexes, condition variables, spin locks or other similar thread synchronisation primitives is unspecified under all concurrency models.

The internal consumption by OpenSSL of threads is unspecified under the Thread-Assisted Concurrency Model.

The internal consumption by OpenSSL of sockets, socket-like OS handles or file descriptors, or other resources as needed to support inter-thread notification, is unspecified under the Thread-Assisted Concurrency Model or when using SSL_DOMAIN_FLAG_BLOCKING.

A QUIC SSL object has blocking mode enabled by default where all of the following criteria are met:

• SSL_DOMAIN_FLAG_BLOCKING or SSL_DOMAIN_FLAG_LEGACY_BLOCKING is enabled; and
• The QUIC connection is being used with network read and write BIOs which expose supported poll descriptors. See openssl-quic(7) for details.

In all other cases, a QUIC SSL object has blocking mode disabled by default. The blocking mode can be changed explicitly using SSL_set_blocking_mode(3).

openssl-quic(7), SSL_handle_events(3), SSL_get_event_timeout(3), OSSL_QUIC_client_thread_method(3), SSL_CTX_set_domain_flags(3), SSL_new_domain(3)

Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License").  You may not use this file except in compliance with the License.  You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.

openssl-quic.7ossl(7), SSL_CTX_set_domain_flags.3ossl(3), SSL_new_domain.3ossl(3), SSL_new_listener.3ossl(3), SSL_set_blocking_mode.3ossl(3).