You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by ac...@apache.org on 2017/09/14 18:17:49 UTC
qpid-proton git commit: PROTON-1543: c++ doc improvements
Repository: qpid-proton
Updated Branches:
refs/heads/master acfe8a3b3 -> e07d4fe73
PROTON-1543: c++ doc improvements
- container.hpp and mt.md: more explanation of recommended "handler-per-connection" approach
- minor clarifications
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/e07d4fe7
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/e07d4fe7
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/e07d4fe7
Branch: refs/heads/master
Commit: e07d4fe73a8151d23c5d17eb986013e65d7fb435
Parents: acfe8a3
Author: Alan Conway <ac...@redhat.com>
Authored: Thu Sep 14 14:16:10 2017 -0400
Committer: Alan Conway <ac...@redhat.com>
Committed: Thu Sep 14 14:17:31 2017 -0400
----------------------------------------------------------------------
proton-c/bindings/cpp/docs/main.md | 5 ++-
proton-c/bindings/cpp/docs/mt.md | 34 +++++++++++------
.../bindings/cpp/include/proton/container.hpp | 40 +++++++++++++-------
.../bindings/cpp/include/proton/thread_safe.hpp | 5 +--
4 files changed, 54 insertions(+), 30 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e07d4fe7/proton-c/bindings/cpp/docs/main.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/main.md b/proton-c/bindings/cpp/docs/main.md
index e7eb212..798ac4b 100644
--- a/proton-c/bindings/cpp/docs/main.md
+++ b/proton-c/bindings/cpp/docs/main.md
@@ -64,5 +64,6 @@ Address URLs (`addr_url`) extend the connection URL to reference an
AMQP node such as a queue or topic. The path of the URL, minus the
leading slash, is treated as the AMQP address of the node.
-Listener URLs (`listen_url`) specify a local network address and port
-for accepting incoming TCP connections.
+Listener URLs (`listen_url`) specify a local network address and port for
+accepting incoming TCP connections. The path part of the URL is ignored.
+The host part may be empty, meaning "listen on all available interfaces".
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e07d4fe7/proton-c/bindings/cpp/docs/mt.md
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/docs/mt.md b/proton-c/bindings/cpp/docs/mt.md
index 5b60278..293290c 100644
--- a/proton-c/bindings/cpp/docs/mt.md
+++ b/proton-c/bindings/cpp/docs/mt.md
@@ -4,22 +4,31 @@ Full multithreading support is available with C++11 and later. Limited
multithreading is possible with older versions of C++. See the last
section of this page for more information.
-## Thread-safety rules
+The `proton::container` handles multiple connections concurrently in a thread
+pool, created using `proton::container::run()`. As AMQP events occur on a
+connection the container calls `proton::messaging_handler` event callbacks. The
+calls for each connection are *serialized* - callbacks for the same connection
+are never made concurrently.
-`proton::message` is a value type with the same threading constraints
-as a standard C++ built-in type. It cannot be concurrently modified.
-The `proton::container` is thread-safe *with C++11 or greater*. It has
-the following capabilities.
+You assign a handler to a connection in `proton::container::connect()` or
+`proton::listen_handler::on_accept()` with
+`proton::connection_options::handler()`. We recommend you create a separate
+handler for each connection. That means the handler doesn't need locks or other
+synchronization to protect it against concurrent use by proton threads.
+(If you use the handler concurrently from non-proton threads then you will need
+synchronization.)
- * Application threads can open (or listen for) new connections at any
- time.
+The examples @ref multithreaded_client.cpp and @ref
+multithreaded_client_flow_control.cpp illustrate these points.
- * It manages worker threads to process connections.
- * It handles network IO and calls the relevant
- `proton::messaging_handler` event callbacks to execute application
- code.
+## Thread-safety rules
+
+The `proton::container` is thread-safe *with C++11 or greater*. An application
+thread can open (or listen for) new connections at any time. The container uses
+threads that call proton::container::run() to handle network IO, and call
+user-defined `proton::messaging_handler` callbacks.
The `proton::container` ensures that calls to event callbacks for each
connection instance are *serialized* (not called concurrently), but
@@ -41,6 +50,9 @@ thread-safe and are subject to the following rules.
3. You can store Proton objects in member variables for use in a later
callback, provided you respect rule two.
+`proton::message` is a value type with the same threading constraints
+as a standard C++ built-in type. It cannot be concurrently modified.
+
## Work queues
`proton::work_queue` provides a safe way to communicate between
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e07d4fe7/proton-c/bindings/cpp/include/proton/container.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/container.hpp b/proton-c/bindings/cpp/include/proton/container.hpp
index b37bfd8..64caa15 100644
--- a/proton-c/bindings/cpp/include/proton/container.hpp
+++ b/proton-c/bindings/cpp/include/proton/container.hpp
@@ -54,25 +54,31 @@ namespace proton {
/// messages.
class PN_CPP_CLASS_EXTERN container {
public:
- /// Create a container with a handler for messaging events.
+ /// Create a container with a global handler for messaging events.
///
- /// The optional `id` parameter sets the container's unique
- /// identity.
+ /// **Thread safety** - in a multi-threaded container this handler will be
+ /// called concurrently. You can use locks to make that safe, or use a
+ /// separate handler for each connection. See @ref mt_page.
+ ///
+ /// @param handler global handler, called for events on all connections
+ /// managed by the container.
+ ///
+ /// @param id sets the container's unique identity.
PN_CPP_EXTERN container(messaging_handler& handler, const std::string& id="");
/// Create a container.
- ///
- /// @copydetails container()
+ /// @param id sets the container's unique identity.
PN_CPP_EXTERN container(const std::string& id="");
/// Destroy a container.
///
- /// **Thread safety** - It is unsafe to delete a container from
- /// within any of the threads running a `messaging_handler`.
- /// Deleting the container from within a handler will cause a
- /// deadlock or crash. The only safe place to delete a container
- /// is after all of the threads running a container have finished
- /// and all of the `run()` functions have returned.
+ /// A container must not be destroyed while a call to run() is in progress,
+ /// in particular it must not be destroyed from a @ref messaging_handler
+ /// callback.
+ ///
+ /// **Thread safety** - in a multi-threaded application, run() must return
+ /// in all threads that call it before destroying the container.
+ ///
PN_CPP_EXTERN ~container();
/// Connect to `conn_url` and send an open request to the remote
@@ -99,6 +105,9 @@ class PN_CPP_CLASS_EXTERN container {
/// Listen for new connections on `listen_url`.
///
+ /// listen_handler::on_accept is called for each incoming connection to determine
+ /// the @ref connection_options to use, including the @ref messaging_handler.
+ ///
/// **Thread safety** - Calls to `listen_handler` methods
/// are serialized for this listener, but handlers attached to
/// separate listeners can be safely called concurrently.
@@ -109,13 +118,18 @@ class PN_CPP_CLASS_EXTERN container {
///
/// Use a fixed set of options for all accepted connections. See
/// listen(const std::string&, listen_handler&).
+ ///
+ /// **Thread safety** - for multi-threaded applications we recommend using a
+ /// @ref listen_handler to create a new @ref messaging_handler for each connection.
+ /// See listen(const std::string&, listen_handler&) and @ref mt_page
PN_CPP_EXTERN listener listen(const std::string& listen_url,
const connection_options& conn_opts);
/// @copybrief listen
///
/// New connections will use the handler from
- /// `server_connection_options()`.
+ /// `server_connection_options()`. See listen(const std::string&, const
+ /// connection_options&);
PN_CPP_EXTERN listener listen(const std::string& listen_url);
/// Run the container in the current thread.
@@ -129,7 +143,7 @@ class PN_CPP_CLASS_EXTERN container {
PN_CPP_EXTERN void run();
#if PN_CPP_SUPPORTS_THREADS
- /// Run the container with a pool of `count` threads.
+ /// Run the container with a pool of `count` threads, including the current thread.
///
/// **C++ versions** - Available with C++11 or later.
///
http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/e07d4fe7/proton-c/bindings/cpp/include/proton/thread_safe.hpp
----------------------------------------------------------------------
diff --git a/proton-c/bindings/cpp/include/proton/thread_safe.hpp b/proton-c/bindings/cpp/include/proton/thread_safe.hpp
index e0d1789..81b10b1 100644
--- a/proton-c/bindings/cpp/include/proton/thread_safe.hpp
+++ b/proton-c/bindings/cpp/include/proton/thread_safe.hpp
@@ -20,9 +20,6 @@
* under the License.
*/
-/// @file
-///
-/// **Deprecated** - Container method return values are safe to
-/// use only inside handlers.
+// Removed. Place-holder for for #include compatibility.
#endif // PROTON_THREAD_SAFE_HPP
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org