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
