From 45abc54125e59f816f3d17d1dcbb66c8ae4578aa Mon Sep 17 00:00:00 2001 From: Christopher Kohlhoff Date: Thu, 7 Mar 2019 15:19:13 +1100 Subject: [PATCH] Fix up dispatch() documentation. Clarify distinction between post() and defer(). --- asio/include/asio/defer.hpp | 10 ++++++++++ asio/include/asio/dispatch.hpp | 8 ++++---- asio/include/asio/post.hpp | 6 ++++++ asio/src/doc/reference.qbk | 12 ++++++++++-- 4 files changed, 30 insertions(+), 6 deletions(-) diff --git a/asio/include/asio/defer.hpp b/asio/include/asio/defer.hpp index 04bccdb0..4f338402 100644 --- a/asio/include/asio/defer.hpp +++ b/asio/include/asio/defer.hpp @@ -31,6 +31,11 @@ namespace asio { * executor. The function object is queued for execution, and is never called * from the current thread prior to returning from defer(). * + * The use of @c defer(), rather than @ref post(), indicates the caller's + * preference that the executor defer the queueing of the function object. This + * may allow the executor to optimise queueing for cases when the function + * object represents a continuation of the current call context. + * * This function has the following effects: * * @li Constructs a function object handler of type @c Handler, initialized @@ -59,6 +64,11 @@ ASIO_INITFN_RESULT_TYPE(CompletionToken, void()) defer( * The function object is queued for execution, and is never called from the * current thread prior to returning from defer(). * + * The use of @c defer(), rather than @ref post(), indicates the caller's + * preference that the executor defer the queueing of the function object. This + * may allow the executor to optimise queueing for cases when the function + * object represents a continuation of the current call context. + * * This function has the following effects: * * @li Constructs a function object handler of type @c Handler, initialized diff --git a/asio/include/asio/dispatch.hpp b/asio/include/asio/dispatch.hpp index f1e05520..f5bed082 100644 --- a/asio/include/asio/dispatch.hpp +++ b/asio/include/asio/dispatch.hpp @@ -28,8 +28,8 @@ namespace asio { /// Submits a completion token or function object for execution. /** * This function submits an object for execution using the object's associated - * executor. The function object is queued for execution, and is never called - * from the current thread prior to returning from dispatch(). + * executor. The function object may be called from the current thread prior to + * returning from dispatch(). Otherwise, it is queued for execution. * * This function has the following effects: * @@ -56,8 +56,8 @@ ASIO_INITFN_RESULT_TYPE(CompletionToken, void()) dispatch( /// Submits a completion token or function object for execution. /** * This function submits an object for execution using the specified executor. - * The function object is queued for execution, and is never called from the - * current thread prior to returning from dispatch(). + * The function object may be called from the current thread prior to returning + * from dispatch(). Otherwise, it is queued for execution. * * This function has the following effects: * diff --git a/asio/include/asio/post.hpp b/asio/include/asio/post.hpp index f840b1b6..40645e13 100644 --- a/asio/include/asio/post.hpp +++ b/asio/include/asio/post.hpp @@ -31,6 +31,9 @@ namespace asio { * executor. The function object is queued for execution, and is never called * from the current thread prior to returning from post(). * + * The use of @c post(), rather than @ref defer(), indicates the caller's + * preference that the function object be eagerly queued for execution. + * * This function has the following effects: * * @li Constructs a function object handler of type @c Handler, initialized @@ -59,6 +62,9 @@ ASIO_INITFN_RESULT_TYPE(CompletionToken, void()) post( * The function object is queued for execution, and is never called from the * current thread prior to returning from post(). * + * The use of @c post(), rather than @ref defer(), indicates the caller's + * preference that the function object be eagerly queued for execution. + * * This function has the following effects: * * @li Constructs a function object handler of type @c Handler, initialized diff --git a/asio/src/doc/reference.qbk b/asio/src/doc/reference.qbk index 1440fc19..6d000174 100644 --- a/asio/src/doc/reference.qbk +++ b/asio/src/doc/reference.qbk @@ -58529,6 +58529,8 @@ Submits a completion token or function object for execution. This function submits an object for execution using the object's associated executor. The function object is queued for execution, and is never called from the current thread prior to returning from `defer()`. +The use of `defer()`, rather than [link asio.reference.post `post`] , indicates the caller's preference that the executor defer the queueing of the function object. This may allow the executor to optimise queueing for cases when the function object represents a continuation of the current call context. + This function has the following effects: @@ -58573,6 +58575,8 @@ Submits a completion token or function object for execution. This function submits an object for execution using the specified executor. The function object is queued for execution, and is never called from the current thread prior to returning from `defer()`. +The use of `defer()`, rather than [link asio.reference.post `post`] , indicates the caller's preference that the executor defer the queueing of the function object. This may allow the executor to optimise queueing for cases when the function object represents a continuation of the current call context. + This function has the following effects: @@ -58756,7 +58760,7 @@ Submits a completion token or function object for execution. CompletionToken && token); -This function submits an object for execution using the object's associated executor. The function object is queued for execution, and is never called from the current thread prior to returning from `dispatch()`. +This function submits an object for execution using the object's associated executor. The function object may be called from the current thread prior to returning from `dispatch()`. Otherwise, it is queued for execution. This function has the following effects: @@ -58800,7 +58804,7 @@ Submits a completion token or function object for execution. typename enable_if< is_executor< Executor >::value >::type * = 0); -This function submits an object for execution using the specified executor. The function object is queued for execution, and is never called from the current thread prior to returning from `dispatch()`. +This function submits an object for execution using the specified executor. The function object may be called from the current thread prior to returning from `dispatch()`. Otherwise, it is queued for execution. This function has the following effects: @@ -98100,6 +98104,8 @@ Submits a completion token or function object for execution. This function submits an object for execution using the object's associated executor. The function object is queued for execution, and is never called from the current thread prior to returning from `post()`. +The use of `post()`, rather than [link asio.reference.defer `defer`] , indicates the caller's preference that the function object be eagerly queued for execution. + This function has the following effects: @@ -98144,6 +98150,8 @@ Submits a completion token or function object for execution. This function submits an object for execution using the specified executor. The function object is queued for execution, and is never called from the current thread prior to returning from `post()`. +The use of `post()`, rather than [link asio.reference.defer `defer`] , indicates the caller's preference that the function object be eagerly queued for execution. + This function has the following effects: