This is an automated email from the ASF dual-hosted git repository. asf-gitbox-commits pushed a commit to branch main in repository https://gitbox.apache.org/repos/asf/qpid-proton.git
commit 9a1664f2b4b66d924e56b6a4238ea876121d9d25 Author: Andrew Stitcher <[email protected]> AuthorDate: Mon May 11 17:10:44 2026 -0400 NO-JIRA: [C++ docs] Improvements to description of proton::work_queue --- cpp/docs/mt.md | 6 +++++- cpp/include/proton/work_queue.hpp | 18 +++++++++++++----- 2 files changed, 18 insertions(+), 6 deletions(-) diff --git a/cpp/docs/mt.md b/cpp/docs/mt.md index 3be1bc22f..6ceca3b99 100644 --- a/cpp/docs/mt.md +++ b/cpp/docs/mt.md @@ -60,7 +60,7 @@ connection handlers. * Each connection has an associated `proton::work_queue`. - * The work queue is thread-safe (C++11 or greater). Any thread can + * The work queue is thread-safe. Any thread can add *work*. * *Work* is a `std::function`, and bound arguments will be @@ -70,6 +70,10 @@ When the work function is called by Proton, it will be serialized safely so that you can treat the work function like an event callback and safely access the handler and Proton objects stored on it. +It is possible to create free standing `proton::work_queue`s which are +backed by a container, in this case the *work* will be serialised with +other container callbacks, but not with connection callbacks. + The examples @ref multithreaded_client.cpp and @ref multithreaded_client_flow_control.cpp show how you can send and receive messages from non-Proton threads using work queues. diff --git a/cpp/include/proton/work_queue.hpp b/cpp/include/proton/work_queue.hpp index defe1aaa7..b0b60f897 100644 --- a/cpp/include/proton/work_queue.hpp +++ b/cpp/include/proton/work_queue.hpp @@ -313,13 +313,15 @@ using internal::v11::make_work; /// Event-handler functions associated with a single /// `proton::connection` are called in sequence. The connection's /// `proton::work_queue` allows you to "inject" extra work from -/// any thread and have it executed in the same sequence. +/// any thread and have it executed in the same sequence in the +/// serialized context of the connection. That is the event loop / driver thread +/// that runs that connection's callbacks not on the calling thread. /// /// You may also create arbitrary `proton::work_queue` objects backed /// by a @ref container that allow other objects to have their own -/// serialised work queues that can have work injected safely from +/// serialized work queues that can have work injected safely from /// other threads. The @ref container ensures that the work is -/// correctly serialised. +/// correctly serialized and run on a thread that is running the container. /// /// The `proton::work` class represents the work to be queued and can /// be created from a function that takes no parameters and returns no @@ -342,10 +344,16 @@ class PN_CPP_CLASS_EXTERN work_queue { /// **Unsettled API** - Add work `fn` to the work queue. /// /// Work `fn` will be called serially with other work in the queue. - /// The work may be deferred and executed in another thread. + /// The work will be deferred and executed on the connection thread associated + /// with the owner of the work queue. It will be executed serially with any + /// callbacks associated with that connection. + /// + /// If the work queue is backed by a container, the work will be executed on + /// a thread that is running the container, but there are no guarantees about how + /// it will be serialized with any connection callbacks in that container. /// /// @return true if `fn` has been or will be called; false if the - /// event loops is ended or `fn` cannot be injected for any other + /// event loops are ended or `fn` cannot be injected for any other /// reason. PN_CPP_EXTERN bool add(work fn); --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
