diff --git a/doc/reference.dox b/doc/reference.dox index 25e915c4..4992521e 100644 --- a/doc/reference.dox +++ b/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 = diff --git a/doc/reference.qbk b/doc/reference.qbk index bb060cd9..35b6906f 100644 --- a/doc/reference.qbk +++ b/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] diff --git a/doc/reference.xsl b/doc/reference.xsl index 3c134a3b..5efbcd74 100644 --- a/doc/reference.xsl +++ b/doc/reference.xsl @@ -734,6 +734,11 @@ ] + + [link boost_asio.reference.asynchronous_operations + + ] + [link boost_asio.reference.asynchronous_operations.completion_tokens_and_handlers diff --git a/doc/requirements_dox.txt b/doc/requirements_dox.txt new file mode 100644 index 00000000..1ddd6958 --- /dev/null +++ b/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 +*/ diff --git a/include/boost/asio/basic_signal_set.hpp b/include/boost/asio/basic_signal_set.hpp index 8e3450e8..81e7f985 100644 --- a/include/boost/asio/basic_signal_set.hpp +++ b/include/boost/asio/basic_signal_set.hpp @@ -588,6 +588,11 @@ public: * @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))