Debian Codegraph @

upstream/debian-unstable/man7/openssl-quic-concurrency.7ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "OPENSSL-QUIC-CONCURRENCY 7SSL"
58 .TH OPENSSL-QUIC-CONCURRENCY 7SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 openssl\-quic\-concurrency \- OpenSSL QUIC Concurrency Model
65 .SH DESCRIPTION
66 .IX Header "DESCRIPTION"
67 A QUIC domain is a group of QUIC resources such as listeners (see
68 \&\fBSSL_new_listener\fR\|(3)) and connections which share common event processing
69 resources, such as internal pollers, timers and locks. All usage of OpenSSL QUIC
70 happens inside a QUIC domain.
71 .PP
72 These resources can be accessed and used concurrently depending on the
73 circumstances. This man page discusses the available concurrency models and how
74 they can be used.
75 .SH "EXPLICIT AND IMPLICIT QUIC DOMAINS"
76 .IX Header "EXPLICIT AND IMPLICIT QUIC DOMAINS"
77 A QUIC domain is instantiated either explicitly (\fBSSL_new_domain\fR\|(3)) or
78 implicitly by calling \fBSSL_new\fR\|(3) or \fBSSL_new_listener\fR\|(3):
79 .IP \(bu 4
80 An explicit QUIC domain is created by and visible to the application as a QUIC
81 domain SSL object and has other QUIC SSL objects created underneath it, such as
82 listeners or connections.
83 .IP \(bu 4
84 An implicit QUIC domain is one which is created internally due to the direct
85 creation of a QUIC connection or listener SSL object; the application does not
86 explicitly create a QUIC domain SSL object and never directly references the
87 domain.
88 .PP
89 Explicit creation of a QUIC domain provides the greatest level of control for an
90 application. Applications can use an implicit QUIC domain for ease of use and to
91 avoid needing to create a separate QUIC domain SSL object.
92 .PP
93 Regardless of whether a QUIC domain is explicitly created, the internal
94 processing model is the same and the application must choose an appropriate
95 concurrency model as discussed below.
96 .SH "CONCURRENCY MODELS"
97 .IX Header "CONCURRENCY MODELS"
98 The OpenSSL QUIC implementation supports multiple concurrency models to support
99 a wide variety of usage scenarios.
100 .PP
101 The available concurrency models are as follows:
102 .IP \(bu 4
103 The \fBSingle-Threaded Concurrency Model (SCM)\fR, which supports only
104 application-synchronised single-threaded usage.
105 .IP \(bu 4
106 The \fBContentive Concurrency Model (CCM)\fR, which supports multi-threaded usage.
107 .IP \(bu 4
108 The \fBThread-Assisted Concurrency Model (TACM)\fR, which also supports
109 multi-threaded usage and provides assistance to an application for handling QUIC
110 timer events.
111 .PP
112 The merits of these models are as follows:
113 .IP \(bu 4
114 The \fBSingle-Threaded Concurrency Model (SCM)\fR performs no locking or
115 synchronisation. It is entirely up to the application to synchronise access to
116 the QUIC domain and its subsidiary SSL objects.
117 .Sp
118 This concurrency model is also useful for an application which wants to use the
119 OpenSSL QUIC implementation as a pure state machine.
120 .IP \(bu 4
121 The \fBContentive Concurrency Model (CCM)\fR performs automatic locking when making
122 API calls to SSL objects in a QUIC domain. This provides automatic
123 synchronisation for multi-threaded usage of QUIC objects. For example, different
124 QUIC stream SSL objects in the same QUIC connection can be safely accessed from
125 different threads.
126 .Sp
127 This concurrency model adds the overhead of locking over the Single-Threaded
128 Concurrency Model in order to support multi-threaded usage, but provides limited
129 performance in highly contended multi-threaded usage due to its simple approach.
130 However, it may still prove a good solution for a broad class of applications
131 which spend the majority of their time in application logic and not in QUIC I/O
132 processing.
133 .Sp
134 An advantage of this model relative to the more sophisticated concurrency models
135 below is that it does not create any OS threads.
136 .IP \(bu 4
137 The \fBThread-Assisted Concurrency Model (TACM)\fR is identical to the Contentive
138 Concurrency Model except that a thread is spun up in the background to ensure
139 that QUIC timer events are handled in a timely fashion. This ensures that QUIC
140 timeout events are handled even if an application does not periodically call
141 into the QUIC domain to ensure that any outstanding QUIC-related timer or
142 network I/O events are handled. The assist thread contends for the same
143 resources like any other thread. However, handshake layer events (TLS) are never
144 processed by the assist thread.
145 .PP
146 The default concurrency model is CCM or TACM, depending on the \fBSSL_METHOD\fR
147 used with a \fBSSL_CTX\fR. Using \fBOSSL_QUIC_client_method\fR\|(3) results in a default
148 concurrency model of CCM, whereas using \fBOSSL_QUIC_client_thread_method\fR\|(3)
149 results in a default concurrency model of TACM.
150 .PP
151 Additional concurrency models may be offered in future releases of OpenSSL.
152 .SH "BLOCKING I/O CAPABILITIES"
153 .IX Header "BLOCKING I/O CAPABILITIES"
154 All of the supported concurrency models are capable of supporting blocking I/O
155 calls, where application-level I/O calls (for example, to \fBSSL_read_ex\fR\|(3) or
156 \&\fBSSL_write_ex\fR\|(3) on a QUIC stream SSL object) block until the request can be
157 serviced. This includes the use of \fBSSL_poll\fR\|(3) in a blocking fashion.
158 .PP
159 Supporting blocking API calls reliably with multi-threaded usage requires the
160 creation of additional OS resources such as internal file descriptors to allow
161 threads to be woken when necessary. This creation of internal OS resources is
162 optional and may need to be explicitly requested by an application depending on
163 the chosen concurrency model. If this functionality is disabled, depending on
164 the chosen concurrency model, blocking API calls may not be available and calls
165 to \fBSSL_set_blocking_mode\fR\|(3) attempting to enable blocking mode may fail,
166 notwithstanding the following section.
167 .SS "Legacy Blocking Support Compatibility"
168 .IX Subsection "Legacy Blocking Support Compatibility"
169 OpenSSL 3.2 and 3.3 contained a buggy implementation of blocking QUIC I/O calls
170 which is only reliable under single-threaded usage. This functionality is always
171 available in the Single-Threaded Concurrency Model (SCM), where it works
172 reliably.
173 .PP
174 For compatibility reasons, this functionality is also available under the
175 default concurrency model if the application does not explicitly specify a
176 concurrency model or disable it. This is known as Legacy Blocking Compatibility
177 Mode, and its usage is not recommended for multi-threaded applications.
178 .SH "RECOMMENDED USAGE"
179 .IX Header "RECOMMENDED USAGE"
180 New applications are advised to choose a concurrency model as follows:
181 .IP \(bu 4
182 A purely single-threaded application, or an application which wishes to use
183 OpenSSL QUIC as a state machine and manage synchronisation itself, should
184 explicitly select the SCM concurrency model.
185 .IP \(bu 4
186 An application which wants to engage in multi-threaded usage of different QUIC
187 connections or streams in the same QUIC domain should a) select the CCM or TACM
188 concurrency model and b) explicitly opt in or out of blocking I/O support
189 (depending on whether the application wishes to make blocking I/O calls),
190 disabling Legacy Blocking Compatibility Mode.
191 .Sp
192 An application should select the CCM concurrency model if the application can
193 guarantee that a QUIC domain will be serviced regularly (for example, because
194 the application can guarantee that the timeout returned by
195 \&\fBSSL_get_event_timeout\fR\|(3) will be handled). If an application is unable to do
196 this, it should select the TACM concurrency model.
197 .IP \(bu 4
198 Applications should explicitly configure a concurrency model during
199 initialisation.
200 .SH "CONFIGURING A CONCURRENCY MODEL"
201 .IX Header "CONFIGURING A CONCURRENCY MODEL"
202 If using an explicit QUIC domain, a concurrency model is chosen when calling
203 \&\fBSSL_new_domain\fR\|(3) by specifying zero or more of the following flags:
204 .IP \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR 4
205 .IX Item "SSL_DOMAIN_FLAG_SINGLE_THREAD"
206 Specifying this flag configures the Single-Threaded Concurrency Model (SCM).
207 .IP \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR 4
208 .IX Item "SSL_DOMAIN_FLAG_MULTI_THREAD"
209 Specifying this flag configures the Contentive Concurrency Model (CCM) (unless
210 \&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR is also specified).
211 .IP \fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR 4
212 .IX Item "SSL_DOMAIN_FLAG_THREAD_ASSISTED"
213 Specifying this flag configures the Thread-Assisted Concurrency Model (TACM).
214 It implies \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR.
215 .IP \fBSSL_DOMAIN_FLAG_BLOCKING\fR 4
216 .IX Item "SSL_DOMAIN_FLAG_BLOCKING"
217 Enable reliable support for blocking I/O calls, allocating whatever OS resources
218 are necessary to realise this. If this flag is specified,
219 \&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is ignored.
220 .Sp
221 Details on the allocated OS resources can be found under "CONSUMPTION OF OS
222 RESOURCES" below.
223 .IP \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR 4
224 .IX Item "SSL_DOMAIN_FLAG_LEGACY_BLOCKING"
225 Enables legacy blocking compatibility mode. See "Legacy Blocking Support
226 Compatibility".
227 .PP
228 Mutually exclusive flag combinations result in an error (for example, combining
229 \&\fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR and \fBSSL_DOMAIN_FLAG_MULTI_THREADED\fR).
230 .PP
231 The concurrency model for a domain cannot be changed after the domain is
232 created.
233 .SS "Default Behaviour"
234 .IX Subsection "Default Behaviour"
235 If none of \fBSSL_DOMAIN_FLAG_SINGLE_THREAD\fR, \fBSSL_DOMAIN_FLAG_MULTI_THREAD\fR or
236 \&\fBSSL_DOMAIN_FLAG_THREAD_ASSISTED\fR are provided to \fBSSL_new_domain\fR\|(3) or
237 another constructor function which can accept the above flags, the default
238 concurrency model set on the \fBSSL_CTX\fR is used. This default can be set and get
239 using \fBSSL_CTX_set_domain_flags\fR\|(3) and \fBSSL_CTX_get_domain_flags\fR\|(3). Any
240 additional flags provided (for example, \fBSSL_DOMAIN_FLAG_BLOCCKING\fR) are added
241 to the set of inherited flags.
242 .PP
243 The default concurrency model set on a newly created \fBSSL_CTX\fR is determined as
244 follows:
245 .IP \(bu 4
246 If an \fBSSL_METHOD\fR of \fBOSSL_QUIC_client_thread_method\fR\|(3) is used, the
247 Thread-Assisted Concurrency Model (TACM) is used with the
248 \&\fBSSL_DOMAIN_FLAG_BLOCKING\fR flag. This provides reliable blocking functionality.
249 .IP \(bu 4
250 Otherwise, if OpenSSL was built without threading support, the Single-Threaded
251 Concurrency Model (SCM) is used, with the \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR
252 flag.
253 .IP \(bu 4
254 Otherwise, if an \fBSSL_METHOD\fR of \fBOSSL_QUIC_client_method\fR\|(3) is used, the
255 Contentive Concurrency Model (CCM) is used with the
256 \&\fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR flag.
257 .IP \(bu 4
258 Otherwise, the Contentive Concurrency Model (CCM) is used.
259 .PP
260 The default concurrency model may vary between releases of OpenSSL. An
261 application may specify one or more of the domain flags above to ensure
262 consistent usage of a specific concurrency model between releases.
263 .SS "Configuration of Concurrency Models with Implicit QUIC Domains"
264 .IX Subsection "Configuration of Concurrency Models with Implicit QUIC Domains"
265 If an explicit QUIC domain is not explicitly created using \fBSSL_new_domain\fR\|(3),
266 an implicit QUIC domain is created when calling \fBSSL_new_listener\fR\|(3) or
267 \&\fBSSL_new\fR\|(3). Such a domain will use the default domain flags configured on the
268 \&\fBSSL_CTX\fR as described above.
269 .SH "CONSUMPTION OF OS RESOURCES"
270 .IX Header "CONSUMPTION OF OS RESOURCES"
271 If full blocking I/O support is selected using \fBSSL_DOMAIN_FLAG_BLOCKING\fR, at
272 least one socket, socket-like OS handle or file descriptor must be allocated to
273 allow one thread to wake other threads which may be blocking in calls to OS
274 socket polling interfaces such as \fBselect\fR\|(2) or \fBpoll\fR\|(2). This is allocated
275 automatically internally by OpenSSL.
276 .PP
277 If the Thread-Assisted Concurrency Model (TACM) is selected, a background thread
278 is spawned. This also implies \fBSSL_DOMAIN_FLAG_BLOCKING\fR and the above.
279 .PP
280 The internal consumption by OpenSSL of mutexes, condition variables, spin locks
281 or other similar thread synchronisation primitives is unspecified under all
282 concurrency models.
283 .PP
284 The internal consumption by OpenSSL of threads is unspecified under the
285 Thread-Assisted Concurrency Model.
286 .PP
287 The internal consumption by OpenSSL of sockets, socket-like OS handles or file
288 descriptors, or other resources as needed to support inter-thread notification,
289 is unspecified under the Thread-Assisted Concurrency Model or when using
290 \&\fBSSL_DOMAIN_FLAG_BLOCKING\fR.
291 .SH "BEHAVIOUR OF SSL OBJECTS"
292 .IX Header "BEHAVIOUR OF SSL OBJECTS"
293 A QUIC SSL object has blocking mode enabled by default where \fBall\fR of the
294 following criteria are met:
295 .IP \(bu 4
296 \&\fBSSL_DOMAIN_FLAG_BLOCKING\fR or \fBSSL_DOMAIN_FLAG_LEGACY_BLOCKING\fR is enabled;
297 and
298 .IP \(bu 4
299 The QUIC connection is being used with network read and write BIOs which expose
300 supported poll descriptors. See \fBopenssl\-quic\fR\|(7) for details.
301 .PP
302 In all other cases, a QUIC SSL object has blocking mode disabled by default. The
303 blocking mode can be changed explicitly using \fBSSL_set_blocking_mode\fR\|(3).
304 .SH "SEE ALSO"
305 .IX Header "SEE ALSO"
306 \&\fBopenssl\-quic\fR\|(7), \fBSSL_handle_events\fR\|(3), \fBSSL_get_event_timeout\fR\|(3),
307 \&\fBOSSL_QUIC_client_thread_method\fR\|(3), \fBSSL_CTX_set_domain_flags\fR\|(3),
308 \&\fBSSL_new_domain\fR\|(3)
309 .SH COPYRIGHT
310 .IX Header "COPYRIGHT"
311 Copyright 2024\-2025 The OpenSSL Project Authors. All Rights Reserved.
312 .PP
313 Licensed under the Apache License 2.0 (the "License"). You may not use
314 this file except in compliance with the License. You can obtain a copy
315 in the file LICENSE in the source distribution or at
316 <https://www.openssl.org/source/license.html>.