Repository: qpid-proton
Updated Branches:
  refs/heads/master 8c3d7f491 -> 21340cd20


NO-JIRA: [cpp] parameter usage note for messaging_handler


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/21340cd2
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/21340cd2
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/21340cd2

Branch: refs/heads/master
Commit: 21340cd20861118f5442e7b0e348c28dd69f551c
Parents: 8c3d7f4
Author: Alan Conway <acon...@redhat.com>
Authored: Thu Aug 2 11:03:15 2018 -0400
Committer: Alan Conway <acon...@redhat.com>
Committed: Thu Aug 2 11:11:15 2018 -0400

----------------------------------------------------------------------
 cpp/include/proton/messaging_handler.hpp | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/21340cd2/cpp/include/proton/messaging_handler.hpp
----------------------------------------------------------------------
diff --git a/cpp/include/proton/messaging_handler.hpp 
b/cpp/include/proton/messaging_handler.hpp
index 841de7b..6eb3755 100644
--- a/cpp/include/proton/messaging_handler.hpp
+++ b/cpp/include/proton/messaging_handler.hpp
@@ -34,6 +34,30 @@ namespace proton {
 ///
 /// Subclass and override the event-handling member functions.
 ///
+/// Event handling functions can always use the objects passed as
+/// arguments.
+///
+/// @note A handler function **must not** use proton objects that are
+/// not accessible via the arguments passed without taking extra
+/// care. For example an on_message() handler called for connection
+/// "A" cannot simply call sender::send() on a proton::sender
+/// belonging to connection "B".
+///
+/// **Thread-safety**: To be safe for both single- and multi-threaded
+/// use, a handler **must not** directly use objects belonging to
+/// another connection. See @ref mt_page and proton::work_queue for
+/// safe ways to communicate. We recommend writing safe handlers to
+/// avoid mysterious failures if the handler is ever used in a
+/// multi-threaded container.
+///
+/// **Single-threaded only**: An application is single-threaded if it
+/// calls container::run() exactly once, and does not make proton
+/// calls from any other thread. In this case a handler can use
+/// objects belonging to another connection, but it must call
+/// connection::wake() on the other connection before returning.  Such
+/// a handler will fail mysteriously if the container is run with
+/// multiple threads.
+///
 /// #### Close and error handling
 ///
 /// There are several objects that have `on_X_close` and `on_X_error`


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org

Reply via email to