OPENSSL-QUIC-CONCURRENCY(7SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

🌸 OPENSSL-QUIC-CONCURRENCY — the OpenSSL QUIC Concurrency Model, explained by your fave ✨

okay bestie, sit DOWN, because this is openssl-quic-concurrency from the OpenSSL manual (section 7SSL) and it's genuinely one of those pages that looks scary but is actually just telling you how to share your toys nicely 🧸

💖 NAME 💖

openssl-quic-concurrency — the OpenSSL QUIC Concurrency Model. that's it, that's the name, slay.

🌈 DESCRIPTION 🌈

so first things first: a QUIC domain is a group of QUIC resources — think listeners (peep SSL_new_listener(3)) and connections — that all share the same common event-processing resources, like internal pollers, timers and locks. literally every single bit of OpenSSL QUIC usage happens inside a QUIC domain. no exceptions, no cap. 💅

and here's the tea: those resources can be accessed and used concurrently, depending on the circumstances. this man page is gonna walk you through which concurrency models exist and how you actually use them. 🦋

✨ EXPLICIT AND IMPLICIT QUIC DOMAINS ✨

a QUIC domain gets instantiated one of two ways: either explicitly with SSL_new_domain(3), or implicitly by calling SSL_new(3) or SSL_new_listener(3). let's break that down:

  • an explicit QUIC domain is created by the application and visible to it as a QUIC domain SSL object, and it has other QUIC SSL objects created underneath it, like listeners or connections. main character energy fr fr 👑
  • an implicit QUIC domain is one that gets created internally because you directly created a QUIC connection or listener SSL object. the application doesn't explicitly create a QUIC domain SSL object and never directly references the domain. it's giving behind-the-scenes 🎀

creating a QUIC domain explicitly gives you the greatest level of control, periodt. but you can totally use an implicit QUIC domain for ease of use, so you don't have to create a separate QUIC domain SSL object. both work!

and regardless of whether your QUIC domain is explicit or implicit, the internal processing model is the same, and you, yes YOU, must choose an appropriate concurrency model. that's the next section, bestie, don't scroll past it 🙈

💜 CONCURRENCY MODELS 💜

the OpenSSL QUIC implementation supports multiple concurrency models, because it wants to support a wide variety of usage scenarios. very demure, very mindful.

the available concurrency models are:

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

and here are the merits, because we love a pros list:

  • 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. very "I'll handle it myself" of you 💅

  • the Contentive Concurrency Model (CCM) performs automatic locking when making API calls to SSL objects in a QUIC domain. this gives you 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. iconic.

this concurrency model adds the overhead of locking over the Single-Threaded Concurrency Model in order to support multi-threaded usage, but it provides limited performance in highly contended multi-threaded usage because of 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 make sure QUIC timer events are handled in a timely fashion. this ensures QUIC timeout events get handled even if an application doesn't periodically call into the QUIC domain to make sure any outstanding QUIC-related timer or network I/O events are handled. the assist thread contends for the same resources like any other thread. but — and this is important, bestie — handshake layer events (TLS) are never processed by the assist thread. 👀

so what's the default? 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.

and psst — additional concurrency models may be offered in future releases of OpenSSL. so stay tuned, iykyk ⭐

🫶 BLOCKING I/O CAPABILITIES 🫶

all of the supported concurrency models are capable of supporting blocking I/O calls. that means 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. so cozy 💖

but here's the catch: supporting blocking API calls reliably with multi-threaded usage requires the creation of additional OS resources, like internal file descriptors, so threads can 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, then 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. yeah. girl. 😭

🌸 Legacy Blocking Support Compatibility 🌸

okay so this is a lil historical moment. OpenSSL 3.2 and 3.3 contained a buggy implementation of blocking QUIC I/O calls which is only reliable under single-threaded usage. 💀

this functionality is always available in the Single-Threaded Concurrency Model (SCM), where it works reliably. good for her.

for compatibility reasons, this functionality is also available under the default concurrency model if the application does not explicitly specify a concurrency model or disable it. this is known as Legacy Blocking Compatibility Mode, and its usage is not recommended for multi-threaded applications.

🚫 not recommended for multi-threaded apps. don't do it, bestie, i'm begging.

😭 THREAD CANCELLATION 😭

the restrictions in "THREAD CANCELLATION" in openssl-threads(7) also apply to OpenSSL QUIC APIs, including calls used in nonblocking mode. yes, even those.

CCM and TACM use domain-wide synchronisation during API processing. event processing may perform network I/O while it is held, which can be a POSIX cancellation point. interruption can leave later use or teardown of the domain unsafe. 🙈

TACM and CCM with SSL_DOMAIN_FLAG_BLOCKING also maintain internal wait state for blocking calls. if interruption prevents cleanup of this state, later calls on the affected domain can block indefinitely. and SSL_poll(3) can maintain such state in multiple domains in one call. so like, multiple domains, one call, one bad cancellation, chaos. 🔥

because most blocking QUIC functions do not provide a per-call timeout, applications requiring prompt cooperative cancellation should use nonblocking mode and an application-driven event loop, as described in "APPLICATION-DRIVEN EVENT LOOPS" in openssl-quic(7) — waiting for the application cancellation event alongside QUIC events. alternatively, an application can call SSL_poll(3) with a finite timeout and check a cancellation condition between calls. pick your fighter ✨

new applications, listen up: you're advised to choose a concurrency model like this:

  • 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.

and that's a wrap on... wait, no it's not 💅 there's more coming, so don't go anywhere bestie —

CONFIGURING A CONCURRENCY MODEL 💅

okay bestie, so if ur rolling with an explicit QUIC domain, u pick a concurrency model when u call SSL_new_domain(3) — just pass zero or more of these flags and let the vibes settle:

  • SSL_DOMAIN_FLAG_SINGLE_THREAD — this one configures the Single-Threaded Concurrency Model (SCM).
  • SSL_DOMAIN_FLAG_MULTI_THREAD — this configures the Contentive Concurrency Model (CCM), unless SSL_DOMAIN_FLAG_THREAD_ASSISTED is also specified.
  • SSL_DOMAIN_FLAG_THREAD_ASSISTED — configures the Thread-Assisted Concurrency Model (TACM). It implies SSL_DOMAIN_FLAG_MULTI_THREAD.
  • SSL_DOMAIN_FLAG_BLOCKING — turns on reliable support for blocking I/O calls, and allocates whatever OS resources are necessary to make that happen. If this flag is specified, SSL_DOMAIN_FLAG_LEGACY_BLOCKING is ignored. Details on the allocated OS resources live under "CONSUMPTION OF OS RESOURCES" below.
  • SSL_DOMAIN_FLAG_LEGACY_BLOCKING — enables legacy blocking compatibility mode. Go peek at "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. (Yes, bestie, that’s exactly how it’s written. We don’t fix, we just report. 💀)

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

Default Behaviour 🎀

If none of SSL_DOMAIN_FLAG_SINGLE_THREAD, SSL_DOMAIN_FLAG_MULTI_THREAD or SSL_DOMAIN_FLAG_THREAD_ASSISTED are provided to SSL_new_domain(3) — or to another constructor function which can accept the above flags — then the default concurrency model set on the SSL_CTX is used. This default can be set and get using SSL_CTX_set_domain_flags(3) and SSL_CTX_get_domain_flags(3). Any additional flags provided (for example, SSL_DOMAIN_FLAG_BLOCCKING) are added to the set of inherited flags. (Again, that spelling is the original’s, not mine. 🙈)

The default concurrency model set on a newly created SSL_CTX is determined as follows:

  • If an SSL_METHOD of OSSL_QUIC_client_thread_method(3) is used, the Thread-Assisted Concurrency Model (TACM) is used with the SSL_DOMAIN_FLAG_BLOCKING flag. This provides reliable blocking functionality. 🔥
  • Otherwise, if OpenSSL was built without threading support, the Single-Threaded Concurrency Model (SCM) is used, with the SSL_DOMAIN_FLAG_LEGACY_BLOCKING flag.
  • Otherwise, if an SSL_METHOD of OSSL_QUIC_client_method(3) is used, the Contentive Concurrency Model (CCM) is used with the SSL_DOMAIN_FLAG_LEGACY_BLOCKING flag.
  • Otherwise, the Contentive Concurrency Model (CCM) is used.

The default concurrency model may vary between releases of OpenSSL. An application may specify one or more of the domain flags above to ensure consistent usage of a specific concurrency model between releases. so like, if u want stability across versions, be a main character and specify ur flags explicitly. 👑

Configuration of Concurrency Models with Implicit QUIC Domains 🦋

If an explicit QUIC domain is not explicitly created using SSL_new_domain(3), an implicit QUIC domain is created when calling SSL_new_listener(3) or SSL_new(3). Such a domain will use the default domain flags configured on the SSL_CTX as described above.

CONSUMPTION OF OS RESOURCES 😭

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. no cap.

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.

BEHAVIOUR OF SSL OBJECTS ✨

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).

SEE ALSO 👑

Copyright 2024-2026 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>.

and that’s the whole page, bestie 🫶 — it’s from OpenSSL 4.0.3, dated 2026-09-29, and it lives as OPENSSL-QUIC-CONCURRENCY(7SSL). slay, u made it to the end. 💅🌸

📦 where this page comes from