Add documentation note on basic_signal_set's async signal safety.

Author: chriskohlhoff

doc/reference.dox

@@ -127,6 +127,7 @@ INPUT                  = ./../../../boost/asio.hpp \
                          ./../../../boost/asio/experimental \
                          ./model_dox.txt \
                          ./noncopyable_dox.txt \
+                         ./requirements_dox.txt \
                          ./std_exception_dox.txt
 INPUT_ENCODING         = UTF-8
 INPUT_FILE_ENCODING    =

doc/reference.qbk

@@ -6227,7 +6227,7 @@ The [link boost_asio.reference.async_result `async_result`] trait is a customisa
 
 * the operation's internal implementation.
 
-Specialisations of the trait must satisfy the async\_result\_requirements, and are reponsible for determining:
+Specialisations of the trait must satisfy the [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers async_result requirements], and are reponsible for determining:
 
 
 * the concrete completion handler type to be called at the end of the asynchronous operation;
@@ -6246,7 +6246,7 @@ This template may be specialised for user-defined completion token types. The pr
 
 [heading Remarks]
 
-For backwards compatibility, the primary template implements member types and functions that are associated with legacy forms of the [link boost_asio.reference.async_result `async_result`] trait. These are annotated as "Legacy" in the documentation below. User specialisations of this trait do not need to implement these in order to satisfy the async\_result\_requirements.
+For backwards compatibility, the primary template implements member types and functions that are associated with legacy forms of the [link boost_asio.reference.async_result `async_result`] trait. These are annotated as "Legacy" in the documentation below. User specialisations of this trait do not need to implement these in order to satisfy the [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers async_result requirements].
 
 In general, implementers of asynchronous operations should use the async\_initiate function rather than using the [link boost_asio.reference.async_result `async_result`] trait directly. 
 
@@ -10405,7 +10405,7 @@ The [link boost_asio.reference.async_result `async_result`] trait is a customisa
 
 * the operation's internal implementation.
 
-Specialisations of the trait must satisfy the async\_result\_requirements, and are reponsible for determining:
+Specialisations of the trait must satisfy the [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers async_result requirements], and are reponsible for determining:
 
 
 * the concrete completion handler type to be called at the end of the asynchronous operation;
@@ -10424,7 +10424,7 @@ This template may be specialised for user-defined completion token types. The pr
 
 [heading Remarks]
 
-For backwards compatibility, the primary template implements member types and functions that are associated with legacy forms of the [link boost_asio.reference.async_result `async_result`] trait. These are annotated as "Legacy" in the documentation below. User specialisations of this trait do not need to implement these in order to satisfy the async\_result\_requirements.
+For backwards compatibility, the primary template implements member types and functions that are associated with legacy forms of the [link boost_asio.reference.async_result `async_result`] trait. These are annotated as "Legacy" in the documentation below. User specialisations of this trait do not need to implement these in order to satisfy the [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers async_result requirements].
 
 In general, implementers of asynchronous operations should use the async\_initiate function rather than using the [link boost_asio.reference.async_result `async_result`] trait directly. 
 
@@ -43783,6 +43783,11 @@ This asynchronous operation supports cancellation for the following [link boost_
 * `cancellation_type::total` 
 
 
+[heading Remarks]
+      
+Unlike the POSIX function `signal`, `async_wait` executes its completion handler as specified in the [link boost_asio.reference.asynchronous_operations asynchronous operation requirements]. This means it places no async-signal safety restrictions on what work can be performed in a completion handler. 
+
+
 
 
 [endsect]

doc/reference.xsl

@@ -734,6 +734,11 @@
       <xsl:value-of select="."/>
       <xsl:text>]</xsl:text>
     </xsl:when>
+    <xsl:when test="@refid = 'async_op_requirements'">
+      <xsl:text>[link boost_asio.reference.asynchronous_operations </xsl:text>
+      <xsl:value-of select="."/>
+      <xsl:text>]</xsl:text>
+    </xsl:when>
     <xsl:when test="@refid = 'async_result_requirements'">
       <xsl:text>[link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers </xsl:text>
       <xsl:value-of select="."/>

doc/requirements_dox.txt

@@ -0,0 +1,14 @@
+//
+// Copyright (c) 2003-2025 Christopher M. Kohlhoff (chris at kohlhoff dot com)
+//
+// Distributed under the Boost Software License, Version 1.0. (See accompanying
+// file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)
+//
+
+/**
+\page async_op_requirements asynchronous operation requirements
+*/
+
+/**
+\page async_result_requirements @c async_result requirements
+*/

include/boost/asio/basic_signal_set.hpp

@@ -588,6 +588,11 @@ class basic_signal_set : public signal_set_base
    * @li @c cancellation_type::partial
    *
    * @li @c cancellation_type::total
+   *
+   * @note Unlike the POSIX function @c signal, @c async_wait executes its
+   * completion handler as specified in the @ref async_op_requirements. This
+   * means it places no async-signal safety restrictions on what work can be
+   * performed in a completion handler.
    */
   template <
     BOOST_ASIO_COMPLETION_TOKEN_FOR(void (boost::system::error_code, int))