1=pod 2 3=head1 NAME 4 5openssl-quic-concurrency - OpenSSL QUIC Concurrency Model 6 7=head1 DESCRIPTION 8 9A QUIC domain is a group of QUIC resources such as listeners (see 10L<SSL_new_listener(3)>) and connections which share common event processing 11resources, such as internal pollers, timers and locks. All usage of OpenSSL QUIC 12happens inside a QUIC domain. 13 14These resources can be accessed and used concurrently depending on the 15circumstances. This man page discusses the available concurrency models and how 16they can be used. 17 18=head1 EXPLICIT AND IMPLICIT QUIC DOMAINS 19 20A QUIC domain is instantiated either explicitly (L<SSL_new_domain(3)>) or 21implicitly by calling L<SSL_new(3)> or L<SSL_new_listener(3)>: 22 23=over 4 24 25=item 26 27An explicit QUIC domain is created by and visible to the application as a QUIC 28domain SSL object and has other QUIC SSL objects created underneath it, such as 29listeners or connections. 30 31=item 32 33An implicit QUIC domain is one which is created internally due to the direct 34creation of a QUIC connection or listener SSL object; the application does not 35explicitly create a QUIC domain SSL object and never directly references the 36domain. 37 38=back 39 40Explicit creation of a QUIC domain provides the greatest level of control for an 41application. Applications can use an implicit QUIC domain for ease of use and to 42avoid needing to create a separate QUIC domain SSL object. 43 44Regardless of whether a QUIC domain is explicitly created, the internal 45processing model is the same and the application must choose an appropriate 46concurrency model as discussed below. 47 48=head1 CONCURRENCY MODELS 49 50The OpenSSL QUIC implementation supports multiple concurrency models to support 51a wide variety of usage scenarios. 52 53The available concurrency models are as follows: 54 55=over 4 56 57=item * 58 59The B<Single-Threaded Concurrency Model (SCM)>, which supports only 60application-synchronised single-threaded usage. 61 62=item * 63 64The B<Contentive Concurrency Model (CCM)>, which supports multi-threaded usage. 65 66=item * 67 68The B<Thread-Assisted Concurrency Model (TACM)>, which also supports 69multi-threaded usage and provides assistance to an application for handling QUIC 70timer events. 71 72=back 73 74The merits of these models are as follows: 75 76=over 4 77 78=item * 79 80The B<Single-Threaded Concurrency Model (SCM)> performs no locking or 81synchronisation. It is entirely up to the application to synchronise access to 82the QUIC domain and its subsidiary SSL objects. 83 84This concurrency model is also useful for an application which wants to use the 85OpenSSL QUIC implementation as a pure state machine. 86 87=item * 88 89The B<Contentive Concurrency Model (CCM)> performs automatic locking when making 90API calls to SSL objects in a QUIC domain. This provides automatic 91synchronisation for multi-threaded usage of QUIC objects. For example, different 92QUIC stream SSL objects in the same QUIC connection can be safely accessed from 93different threads. 94 95This concurrency model adds the overhead of locking over the Single-Threaded 96Concurrency Model in order to support multi-threaded usage, but provides limited 97performance in highly contended multi-threaded usage due to its simple approach. 98However, it may still prove a good solution for a broad class of applications 99which spend the majority of their time in application logic and not in QUIC I/O 100processing. 101 102An advantage of this model relative to the more sophisticated concurrency models 103below is that it does not create any OS threads. 104 105=item * 106 107The B<Thread-Assisted Concurrency Model (TACM)> is identical to the Contentive 108Concurrency Model except that a thread is spun up in the background to ensure 109that QUIC timer events are handled in a timely fashion. This ensures that QUIC 110timeout events are handled even if an application does not periodically call 111into the QUIC domain to ensure that any outstanding QUIC-related timer or 112network I/O events are handled. The assist thread contends for the same 113resources like any other thread. However, handshake layer events (TLS) are never 114processed by the assist thread. 115 116=back 117 118The default concurrency model is CCM or TACM, depending on the B<SSL_METHOD> 119used with a B<SSL_CTX>. Using L<OSSL_QUIC_client_method(3)> results in a default 120concurrency model of CCM, whereas using L<OSSL_QUIC_client_thread_method(3)> 121results in a default concurrency model of TACM. 122 123Additional concurrency models may be offered in future releases of OpenSSL. 124 125=head1 BLOCKING I/O CAPABILITIES 126 127All of the supported concurrency models are capable of supporting blocking I/O 128calls, where application-level I/O calls (for example, to L<SSL_read_ex(3)> or 129L<SSL_write_ex(3)> on a QUIC stream SSL object) block until the request can be 130serviced. This includes the use of L<SSL_poll(3)> in a blocking fashion. 131 132Supporting blocking API calls reliably with multi-threaded usage requires the 133creation of additional OS resources such as internal file descriptors to allow 134threads to be woken when necessary. This creation of internal OS resources is 135optional and may need to be explicitly requested by an application depending on 136the chosen concurrency model. If this functionality is disabled, depending on 137the chosen concurrency model, blocking API calls may not be available and calls 138to L<SSL_set_blocking_mode(3)> attempting to enable blocking mode may fail, 139notwithstanding the following section. 140 141=head2 Legacy Blocking Support Compatibility 142 143OpenSSL 3.2 and 3.3 contained a buggy implementation of blocking QUIC I/O calls 144which is only reliable under single-threaded usage. This functionality is always 145available in the Single-Threaded Concurrency Model (SCM), where it works 146reliably. 147 148For compatibility reasons, this functionality is also available under the 149default concurrency model if the application does not explicitly specify a 150concurrency model or disable it. This is known as Legacy Blocking Compatibility 151Mode, and its usage is not recommended for multi-threaded applications. 152 153=head1 RECOMMENDED USAGE 154 155New applications are advised to choose a concurrency model as follows: 156 157=over 4 158 159=item * 160 161A purely single-threaded application, or an application which wishes to use 162OpenSSL QUIC as a state machine and manage synchronisation itself, should 163explicitly select the SCM concurrency model. 164 165=item * 166 167An application which wants to engage in multi-threaded usage of different QUIC 168connections or streams in the same QUIC domain should a) select the CCM or TACM 169concurrency model and b) explicitly opt in or out of blocking I/O support 170(depending on whether the application wishes to make blocking I/O calls), 171disabling Legacy Blocking Compatibility Mode. 172 173An application should select the CCM concurrency model if the application can 174guarantee that a QUIC domain will be serviced regularly (for example, because 175the application can guarantee that the timeout returned by 176L<SSL_get_event_timeout(3)> will be handled). If an application is unable to do 177this, it should select the TACM concurrency model. 178 179=item * 180 181Applications should explicitly configure a concurrency model during 182initialisation. 183 184=back 185 186=head1 CONFIGURING A CONCURRENCY MODEL 187 188If using an explicit QUIC domain, a concurrency model is chosen when calling 189L<SSL_new_domain(3)> by specifying zero or more of the following flags: 190 191=over 4 192 193=item B<SSL_DOMAIN_FLAG_SINGLE_THREAD> 194 195Specifying this flag configures the Single-Threaded Concurrency Model (SCM). 196 197=item B<SSL_DOMAIN_FLAG_MULTI_THREAD> 198 199Speciyfing this flag configures the Contentive Concurrency Model (CCM) (unless 200B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> is also specified). 201 202=item B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> 203 204Specifying this flag configures the Thread-Assisted Concurrency Model (TACM). 205It implies B<SSL_DOMAIN_FLAG_MULTI_THREAD>. 206 207=item B<SSL_DOMAIN_FLAG_BLOCKING> 208 209Enable reliable support for blocking I/O calls, allocating whatever OS resources 210are necessary to realise this. If this flag is specified, 211B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> is ignored. 212 213Details on the allocated OS resources can be found under L</CONSUMPTION OF OS 214RESOURCES> below. 215 216=item B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> 217 218Enables legacy blocking compatibility mode. See L</Legacy Blocking Support 219Compatibility>. 220 221=back 222 223Mutually exclusive flag combinations result in an error (for example, combining 224B<SSL_DOMAIN_FLAG_SINGLE_THREAD> and B<SSL_DOMAIN_FLAG_MULTI_THREADED>). 225 226The concurrency model for a domain cannot be changed after the domain is 227created. 228 229=head2 Default Behaviour 230 231If none of B<SSL_DOMAIN_FLAG_SINGLE_THREAD>, B<SSL_DOMAIN_FLAG_MULTI_THREAD> or 232B<SSL_DOMAIN_FLAG_THREAD_ASSISTED> are provided to L<SSL_new_domain(3)> or 233another constructor function which can accept the above flags, the default 234concurrency model set on the B<SSL_CTX> is used. This default can be set and get 235using L<SSL_CTX_set_domain_flags(3)> and L<SSL_CTX_get_domain_flags(3)>. Any 236additional flags provided (for example, B<SSL_DOMAIN_FLAG_BLOCCKING>) are added 237to the set of inherited flags. 238 239The default concurrency model set on a newly created B<SSL_CTX> is determined as 240follows: 241 242=over 4 243 244=item * 245 246If an B<SSL_METHOD> of L<OSSL_QUIC_client_thread_method(3)> is used, the 247Thread-Assisted Concurrency Model (TACM) is used with the 248B<SSL_DOMAIN_FLAG_BLOCKING> flag. This provides reliable blocking functionality. 249 250=item * 251 252Otherwise, if OpenSSL was built without threading support, the Single-Threaded 253Concurrency Model (SCM) is used, with the B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> 254flag. 255 256=item * 257 258Otherwise, if an B<SSL_METHOD> of L<OSSL_QUIC_client_method(3)> is used, the 259Contentive Concurrency Model (CCM) is used with the 260B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> flag. 261 262=item * 263 264Otherwise, the Contentive Concurrency Model (CCM) is used. 265 266=back 267 268The default concurrency model may vary between releases of OpenSSL. An 269application may specify one or more of the domain flags above to ensure 270consistent usage of a specific concurrency model between releases. 271 272=head2 Configuration of Concurrency Models with Implicit QUIC Domains 273 274If an explicit QUIC domain is not explicitly created using L<SSL_new_domain(3)>, 275an implicit QUIC domain is created when calling L<SSL_new_listener(3)> or 276L<SSL_new(3)>. Such a domain will use the default domain flags configured on the 277B<SSL_CTX> as described above. 278 279=head1 CONSUMPTION OF OS RESOURCES 280 281If full blocking I/O support is selected using B<SSL_DOMAIN_FLAG_BLOCKING>, at 282least one socket, socket-like OS handle or file descriptor must be allocated to 283allow one thread to wake other threads which may be blocking in calls to OS 284socket polling interfaces such as select(2) or poll(2). This is allocated 285automatically internally by OpenSSL. 286 287If the Thread-Assisted Concurrency Model (TACM) is selected, a background thread 288is spawned. This also implies B<SSL_DOMAIN_FLAG_BLOCKING> and the above. 289 290The internal consumption by OpenSSL of mutexes, condition variables, spin locks 291or other similar thread synchronisation primitives is unspecified under all 292concurrency models. 293 294The internal consumption by OpenSSL of threads is unspecified under the 295Thread-Assisted Concurrency Model. 296 297The internal consumption by OpenSSL of sockets, socket-like OS handles or file 298descriptors, or other resources as needed to support inter-thread notification, 299is unspecified under the Thread-Assisted Concurrency Model or when using 300B<SSL_DOMAIN_FLAG_BLOCKING>. 301 302=head1 BEHAVIOUR OF SSL OBJECTS 303 304A QUIC SSL object has blocking mode enabled by default where B<all> of the 305following criteria are met: 306 307=over 4 308 309=item * 310 311B<SSL_DOMAIN_FLAG_BLOCKING> or B<SSL_DOMAIN_FLAG_LEGACY_BLOCKING> is enabled; 312and 313 314=item * 315 316The QUIC connection is being used with network read and write BIOs which expose 317supported poll descriptors. See L<openssl-quic(7)> for details. 318 319=back 320 321In all other cases, a QUIC SSL object has blocking mode disabled by default. The 322blocking mode can be changed explicitly using L<SSL_set_blocking_mode(3)>. 323 324=head1 SEE ALSO 325 326L<openssl-quic(7)>, L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>, 327L<OSSL_QUIC_client_thread_method(3)>, L<SSL_CTX_set_domain_flags(3)>, 328L<SSL_new_domain(3)> 329 330=head1 COPYRIGHT 331 332Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved. 333 334Licensed under the Apache License 2.0 (the "License"). You may not use 335this file except in compliance with the License. You can obtain a copy 336in the file LICENSE in the source distribution or at 337L<https://www.openssl.org/source/license.html>. 338 339=cut 340