Commit a0605a85b2 for openssl.org

commit a0605a85b24e135f2da4d870c62b6a7b163e18f2
Author: Mounir IDRASSI <mounir.idrassi@idrix.fr>
Date:   Sun Aug 2 14:41:30 2026 +0900

    doc: document QUIC thread cancellation consequences

    Describe the domain-wide consequences of interrupting QUIC API
    processing while synchronisation is held or notification state is
    registered.

    Clarify that SSL_poll() can leave stale registrations in multiple
    notifier-enabled domains, and provide cooperative cancellation and
    application-driven event-loop guidance.

    Assisted-by: Codex:gpt-5.6-sol
    Reviewed-by: Tomas Mraz <tomas@openssl.foundation>
    Reviewed-by: Andrew Dinh <andrewd@openssl.org>
    Merge-date: Wed Aug 19 10:28:50 2026
    Merged-from: https://github.com/openssl/openssl/pull/32139

diff --git a/doc/man3/SSL_poll.pod b/doc/man3/SSL_poll.pod
index 6047bd6750..be8f8a4f78 100644
--- a/doc/man3/SSL_poll.pod
+++ b/doc/man3/SSL_poll.pod
@@ -337,6 +337,20 @@ stream SSL objects, are supported.

 This limitation may be revised in a future release of OpenSSL.

+=head1 THREAD CANCELLATION
+
+A finite I<timeout> limits ordinary waiting by SSL_poll(), but does not make the
+call safe against thread cancellation; see L<openssl-threads(7)>.
+
+Cancellation can prevent SSL_poll() from removing internal wait state. Because
+an I<items> array can span multiple QUIC domains, one interrupted call can leave
+stale state in several domains and cause later calls on those domains, including
+SSL_poll() with a finite timeout, to block indefinitely.
+
+For cooperative cancellation, use a finite timeout and check a cancellation
+condition between calls; see L<openssl-quic-concurrency(7)/THREAD CANCELLATION>
+for the nonblocking alternative.
+
 =head1 RETURN VALUES

 SSL_poll() returns 1 on success and 0 on failure.
@@ -406,7 +420,9 @@ I<result_count>.
 =head1 SEE ALSO

 L<BIO_get_rpoll_descriptor(3)>, L<BIO_get_wpoll_descriptor(3)>,
-L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>
+L<SSL_get_rpoll_descriptor(3)>, L<SSL_get_wpoll_descriptor(3)>,
+L<openssl-threads(7)>, L<openssl-quic(7)>,
+L<openssl-quic-concurrency(7)>

 =head1 HISTORY

@@ -421,7 +437,7 @@ event types were not present.

 =head1 COPYRIGHT

-Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
+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
diff --git a/doc/man7/openssl-quic-concurrency.pod b/doc/man7/openssl-quic-concurrency.pod
index e79dd2a3a2..7f2e54bcb3 100644
--- a/doc/man7/openssl-quic-concurrency.pod
+++ b/doc/man7/openssl-quic-concurrency.pod
@@ -150,6 +150,29 @@ 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.

+=head1 THREAD CANCELLATION
+
+The restrictions in L<openssl-threads(7)/THREAD CANCELLATION> also apply to
+OpenSSL QUIC APIs, including calls used in nonblocking mode.
+
+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 B<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. L<SSL_poll(3)> can maintain such
+state in multiple domains in one call.
+
+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
+L<openssl-quic(7)/APPLICATION-DRIVEN EVENT LOOPS>, waiting for the application
+cancellation event alongside QUIC events. Alternatively, an application can
+call L<SSL_poll(3)> with a finite timeout and check a cancellation condition
+between calls.
+
 =head1 RECOMMENDED USAGE

 New applications are advised to choose a concurrency model as follows:
@@ -323,13 +346,15 @@ blocking mode can be changed explicitly using L<SSL_set_blocking_mode(3)>.

 =head1 SEE ALSO

-L<openssl-quic(7)>, L<SSL_handle_events(3)>, L<SSL_get_event_timeout(3)>,
+L<openssl-quic(7)>, L<openssl-threads(7)>, L<SSL_handle_events(3)>,
+L<SSL_get_event_timeout(3)>, L<SSL_get_rpoll_descriptor(3)>,
+L<SSL_get_wpoll_descriptor(3)>, L<SSL_poll(3)>,
 L<OSSL_QUIC_client_thread_method(3)>, L<SSL_CTX_set_domain_flags(3)>,
 L<SSL_new_domain(3)>

 =head1 COPYRIGHT

-Copyright 2024-2025 The OpenSSL Project Authors. All Rights Reserved.
+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