PROTON-1543: Various improvements to the C++ API docs - Fix see-alsos in source and target options - Extend docs for connection options; fill in missing docs related to work queues - Fix references to multithread examples - Some copyedits
Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/540622ed Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/540622ed Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/540622ed Branch: refs/heads/go1 Commit: 540622ed46eab6cda148043682f4fa11f0f42367 Parents: 38b27b5 Author: Justin Ross <jr...@apache.org> Authored: Tue Aug 29 19:56:37 2017 -0700 Committer: Justin Ross <jr...@apache.org> Committed: Tue Aug 29 19:56:37 2017 -0700 ---------------------------------------------------------------------- examples/cpp/README.dox | 22 ++++--- proton-c/bindings/cpp/docs/mt.md | 21 +++---- .../bindings/cpp/include/proton/connection.hpp | 23 ++++---- .../cpp/include/proton/connection_options.hpp | 59 +++++++++++-------- .../cpp/include/proton/source_options.hpp | 3 +- .../cpp/include/proton/target_options.hpp | 3 +- .../bindings/cpp/include/proton/work_queue.hpp | 60 +++++++++++++------- 7 files changed, 111 insertions(+), 80 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/examples/cpp/README.dox ---------------------------------------------------------------------- diff --git a/examples/cpp/README.dox b/examples/cpp/README.dox index 551efde..b475b2a 100644 --- a/examples/cpp/README.dox +++ b/examples/cpp/README.dox @@ -7,17 +7,9 @@ // // then open proton-c/bindings/cpp/docs/html/tutorial.html in your browser. -// DEVELOPER NOTE: if you add or modify examples, please add/update a short +// DEVELOPER NOTE: If you add or modify examples, please add/update a short // description below and (if appropriate) extend/update tutorial.dox. -/** example sub directory - -The example sub-directory has utilities classes to make the example simpler, -these classes are not directly related to the use of proton so are in a separate -`example` directory and namespace. - -*/ - /** @example helloworld.cpp Connects to a broker on 127.0.0.1:5672, establishes a subscription @@ -139,12 +131,18 @@ Also provides some general notes on Service Bus usage. */ -/** @example send_recv_mt.cpp +/** @example multithreaded_client.cpp -A multi-threaded sender and receiver. +A multithreaded sender and receiver. __Requires C++11__ */ -*/ \ No newline at end of file +/** @example multithreaded_client_flow_control.cpp + +A multithreaded sender and receiver enhanced for flow control. + +__Requires C++11__ + +*/ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/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 e316f81..4e908bd 100644 --- a/proton-c/bindings/cpp/docs/mt.md +++ b/proton-c/bindings/cpp/docs/mt.md @@ -1,6 +1,7 @@ # Multithreaded Proton applications {#mt_page} -For examples see @ref broker.cpp and @ref send_recv_mt.cpp +For examples see @ref broker.cpp, @ref multithreaded_client.cpp, and +@ref multithreaded_client_flow_control.cpp. Most classes in namespace @ref proton are not thread-safe. Objects belonging to a single connection (`proton::connection`, @@ -12,17 +13,17 @@ A multithreaded container calls event-handling functions for each connection *sequentially* but can process *different* connections concurrently in different threads. If you use a separate `proton::messaging_handler` for each connection, then event-handling -functions can can use their parameters and the handler's own data +functions can use their parameters and the handler's own data members without locks. The handler functions will never be called concurrently. You can set the handlers for each connection using `proton::container::connect()` and `proton::container::listen()`. -The example @ref broker.cpp is a broker that can be run in single or -multi-threaded mode. It creates a new handler for each incoming -connection to manage the state of that connection's `proton::sender` and -`proton::receiver` links. The handler needs no lock because it only deals with -state in the context of one connection. - -The example @ref send_recv_mt.cpp shows how application threads can -communicate safely with proton handler threads. +The example @ref broker.cpp is a broker that can be run in single- or +multithreaded mode. It creates a new handler for each incoming +connection to manage the state of that connection's `proton::sender` +and `proton::receiver` links. The handler needs no lock because it +only deals with state in the context of one connection. +The examples @ref multithreaded_client.cpp and @ref +multithreaded_client_flow_control.cpp show how application threads can +communicate safely with Proton handler threads. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/proton-c/bindings/cpp/include/proton/connection.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/connection.hpp b/proton-c/bindings/cpp/include/proton/connection.hpp index 10ea61b..7888508 100644 --- a/proton-c/bindings/cpp/include/proton/connection.hpp +++ b/proton-c/bindings/cpp/include/proton/connection.hpp @@ -57,7 +57,7 @@ PN_CPP_CLASS_EXTERN connection : public internal::object<pn_connection_t>, publi /// /// @throw proton::error if this connection is not managed by a /// container - PN_CPP_EXTERN class container &container() const; + PN_CPP_EXTERN class container& container() const; /// Get the work_queue for the connection. PN_CPP_EXTERN class work_queue& work_queue() const; @@ -81,7 +81,7 @@ PN_CPP_CLASS_EXTERN connection : public internal::object<pn_connection_t>, publi PN_CPP_EXTERN void open(); /// @copydoc open - PN_CPP_EXTERN void open(const connection_options &); + PN_CPP_EXTERN void open(const connection_options&); PN_CPP_EXTERN void close(); PN_CPP_EXTERN void close(const error_condition&); @@ -90,24 +90,24 @@ PN_CPP_CLASS_EXTERN connection : public internal::object<pn_connection_t>, publi PN_CPP_EXTERN session open_session(); /// @copydoc open_session - PN_CPP_EXTERN session open_session(const session_options &); + PN_CPP_EXTERN session open_session(const session_options&); /// Get the default session. A default session is created on the /// first call and reused for the lifetime of the connection. PN_CPP_EXTERN session default_session(); /// Open a sender for `addr` on default_session(). - PN_CPP_EXTERN sender open_sender(const std::string &addr); + PN_CPP_EXTERN sender open_sender(const std::string& addr); /// @copydoc open_sender - PN_CPP_EXTERN sender open_sender(const std::string &addr, const sender_options &); + PN_CPP_EXTERN sender open_sender(const std::string& addr, const sender_options&); /// Open a receiver for `addr` on default_session(). - PN_CPP_EXTERN receiver open_receiver(const std::string &addr); + PN_CPP_EXTERN receiver open_receiver(const std::string& addr); /// @copydoc open_receiver - PN_CPP_EXTERN receiver open_receiver(const std::string &addr, - const receiver_options &); + PN_CPP_EXTERN receiver open_receiver(const std::string& addr, + const receiver_options&); /// @see proton::container::sender_options() PN_CPP_EXTERN class sender_options sender_options() const; @@ -124,17 +124,18 @@ PN_CPP_CLASS_EXTERN connection : public internal::object<pn_connection_t>, publi /// Return all senders on this connection. PN_CPP_EXTERN sender_range senders() const; - /// Get the maximum frame size. + /// Get the maximum frame size allowed by the remote peer. /// /// @see @ref connection_options::max_frame_size PN_CPP_EXTERN uint32_t max_frame_size() const; - /// Get the maximum number of open sessions. + /// Get the maximum number of open sessions allowed by the remote + /// peer. /// /// @see @ref connection_options::max_sessions PN_CPP_EXTERN uint16_t max_sessions() const; - /// Get the idle timeout. + /// Get the idle timeout set by the remote peer. /// /// @see @ref connection_options::idle_timeout PN_CPP_EXTERN uint32_t idle_timeout() const; http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/proton-c/bindings/cpp/include/proton/connection_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/connection_options.hpp b/proton-c/bindings/cpp/include/proton/connection_options.hpp index 2769a7e..c0ff457 100644 --- a/proton-c/bindings/cpp/include/proton/connection_options.hpp +++ b/proton-c/bindings/cpp/include/proton/connection_options.hpp @@ -79,54 +79,63 @@ class connection_options { /// Set a connection handler. /// - /// The handler must not be deleted until messaging_handler::on_transport_close() is called. + /// The handler must not be deleted until + /// messaging_handler::on_transport_close() is called. PN_CPP_EXTERN connection_options& handler(class messaging_handler&); - /// Set the maximum frame size. + /// Set the maximum frame size. It is unlimited by default. PN_CPP_EXTERN connection_options& max_frame_size(uint32_t max); - /// Set the maximum number of open sessions. + /// Set the maximum number of open sessions. The default value is 32767. PN_CPP_EXTERN connection_options& max_sessions(uint16_t max); - // XXX document relationship to heartbeat interval - /// Set the idle timeout. + /// Set the idle timeout. By default, none is set. + /// + /// If set, the local peer will disconnect if it does not receive + /// AMQP frames before the timeout expires. This serves as + /// "heartbeating", a way to detect dead peers even in the + /// presence of a live TCP connection. PN_CPP_EXTERN connection_options& idle_timeout(duration); /// Set the container ID. - PN_CPP_EXTERN connection_options& container_id(const std::string &id); + PN_CPP_EXTERN connection_options& container_id(const std::string& id); /// Set the virtual host name for the connection. If making a /// client connection by SSL/TLS, this name is also used for /// certificate verification and Server Name Indication. For /// client connections, it defaults to the host name used to set - /// up the connection. It is not set by default for server - /// connections. - PN_CPP_EXTERN connection_options& virtual_host(const std::string &name); + /// up the connection. For server connections, it is not set by + /// default. + PN_CPP_EXTERN connection_options& virtual_host(const std::string& name); - /// Set the user name used to authenticate the connection. + /// Set the user name used to authenticate the connection. It is + /// unset by default. /// - /// This will override any user name that is specified in the url - /// used for container::connect. - /// It will be ignored if the connection is created by container::listen as - /// a listening connection's identity is provided by the remote client. - PN_CPP_EXTERN connection_options& user(const std::string& user); - - /// Set the password used to authenticate the connection - /// It will be ignored if the connection is created by container::listen. - PN_CPP_EXTERN connection_options& password(const std::string& pass); + /// This value overrides any user name that is specified in the + /// URL used for container::connect. It is ignored if the + /// connection is created by container::listen because a listening + /// connection's identity is provided by the remote client. + PN_CPP_EXTERN connection_options& user(const std::string&); + + /// Set the password used to authenticate the connection. It has + /// no default value. + /// + /// This value is ignored if the connection is created by + /// container::listen. + PN_CPP_EXTERN connection_options& password(const std::string&); /// @cond INTERNAL // XXX settle questions about reconnect_timer - consider simply // reconnect_options and making reconnect_timer internal /// **Experimental** - PN_CPP_EXTERN connection_options& reconnect(const reconnect_timer &); + PN_CPP_EXTERN connection_options& reconnect(const reconnect_timer&); /// @endcond /// Set SSL client options. - PN_CPP_EXTERN connection_options& ssl_client_options(const class ssl_client_options &); + PN_CPP_EXTERN connection_options& ssl_client_options(const class ssl_client_options&); /// Set SSL server options. - PN_CPP_EXTERN connection_options& ssl_server_options(const class ssl_server_options &); + PN_CPP_EXTERN connection_options& ssl_server_options(const class ssl_server_options&); /// Enable or disable SASL. PN_CPP_EXTERN connection_options& sasl_enabled(bool); @@ -137,13 +146,13 @@ class connection_options { PN_CPP_EXTERN connection_options& sasl_allow_insecure_mechs(bool); /// Specify the allowed mechanisms for use on the connection. - PN_CPP_EXTERN connection_options& sasl_allowed_mechs(const std::string &); + PN_CPP_EXTERN connection_options& sasl_allowed_mechs(const std::string&); /// **Experimental** - Set the SASL configuration name. - PN_CPP_EXTERN connection_options& sasl_config_name(const std::string &); + PN_CPP_EXTERN connection_options& sasl_config_name(const std::string&); /// **Experimental** - Set the SASL configuration path. - PN_CPP_EXTERN connection_options& sasl_config_path(const std::string &); + PN_CPP_EXTERN connection_options& sasl_config_path(const std::string&); /// Update option values from values set in other. PN_CPP_EXTERN connection_options& update(const connection_options& other); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/proton-c/bindings/cpp/include/proton/source_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/source_options.hpp b/proton-c/bindings/cpp/include/proton/source_options.hpp index f7dde48..19e3cdf 100644 --- a/proton-c/bindings/cpp/include/proton/source_options.hpp +++ b/proton-c/bindings/cpp/include/proton/source_options.hpp @@ -33,7 +33,8 @@ namespace proton { /// Options for creating a source node for a sender or receiver. /// -/// Options can be "chained" (@see proton::connection_options). +/// Options can be "chained". For more information see @ref +/// proton::connection_options. /// /// Normal value semantics: copy or assign creates a separate copy of /// the options. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/proton-c/bindings/cpp/include/proton/target_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/target_options.hpp b/proton-c/bindings/cpp/include/proton/target_options.hpp index 547dbbe..0f2245b 100644 --- a/proton-c/bindings/cpp/include/proton/target_options.hpp +++ b/proton-c/bindings/cpp/include/proton/target_options.hpp @@ -33,7 +33,8 @@ namespace proton { /// Options for creating a target node for a sender or receiver. /// -/// Options can be "chained" (see proton::connection_options). +/// Options can be "chained". For more information see @ref +/// proton::connection_options. /// /// Normal value semantics: copy or assign creates a separate copy of /// the options. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/540622ed/proton-c/bindings/cpp/include/proton/work_queue.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/work_queue.hpp b/proton-c/bindings/cpp/include/proton/work_queue.hpp index 30d8395..2d728fd 100644 --- a/proton-c/bindings/cpp/include/proton/work_queue.hpp +++ b/proton-c/bindings/cpp/include/proton/work_queue.hpp @@ -37,31 +37,27 @@ struct pn_link_t; namespace proton { -/// **Experimental** - A work queue for serial execution. -/// -/// Event handler functions associated with a single proton::connection are called in sequence. -/// The connection's proton::work_queue allows you to "inject" extra @ref work from any thread, -/// and have it executed in the same sequence. -/// -/// 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 other threads. The @ref container ensures that the work is correctly serialised. -/// -/// The @ref work class represents the work to be queued and can be created from a function -/// that takes no parameters and returns no value. -/// - +/// **Experimental** - Work to be queued on a @ref work_queue. It can +/// be created from a function that takes no parameters and returns no +/// value. class work { public: #if PN_CPP_HAS_STD_FUNCTION + /// **Experimental** work(void_function0& f): item_( [&f]() { f(); }) {} + + /// **Experimental** - Construct a unit of work from a + /// std::function. template <class T> work(T f): item_(f) {} + /// **Experimental** void operator()() { item_(); } #else + /// **Experimetnal** work(void_function0& f): item_(&f) {} + /// **Experimetnal** void operator()() { (*item_)(); } #endif ~work() {} @@ -75,28 +71,48 @@ class work { #endif }; +/// **Experimental** - A work queue for serial execution. +/// +/// Event handler functions associated with a single +/// proton::connection are called in sequence. The connection's +/// proton::work_queue allows you to "inject" extra @ref work from any +/// thread, and have it executed in the same sequence. +/// +/// 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 +/// other threads. The @ref container ensures that the work is +/// correctly serialised. +/// +/// The @ref work class represents the work to be queued and can be +/// created from a function that takes no parameters and returns no +/// value. class PN_CPP_CLASS_EXTERN work_queue { - /// @cond internal + /// @cond INTERNAL class impl; work_queue& operator=(impl* i); /// @endcond public: - /// Create work_queue + /// **Experimental** - Create a work_queue. PN_CPP_EXTERN work_queue(); + + /// **Experimental** - Create a work_queue backed by `container`. PN_CPP_EXTERN work_queue(container&); PN_CPP_EXTERN ~work_queue(); - /// Add work to the work queue: f() will be called serialised with other work in the queue: - /// deferred and possibly in another thread. + /// **Experimental** - Add work to the work queue: f() will be + /// called serialised with other work in the queue: deferred and + /// possibly in another thread. /// /// @return true if f() has or will be called, false if the event_loop is ended /// or f() cannot be injected for any other reason. PN_CPP_EXTERN bool add(work f); - /// Add work to the work queue after duration: f() will be called after the duration - /// serialised with other work in the queue: possibly in another thread. + /// **Experimental** - Add work to the work queue after duration: + /// f() will be called after the duration serialised with other + /// work in the queue: possibly in another thread. /// /// The scheduled execution is "best effort" and it is possible that after the elapsed duration /// the work will not be able to be injected into the serialised context - there will be no @@ -347,20 +363,24 @@ void schedule_work(WQ wq, duration dn, F f, A a, B b, C c, D d) { // The C++11 version is *much* simpler and even so more general! // These definitions encompass everything in the C++03 section +/// **Experimental** template <class WQ, class... Rest> bool schedule_work(WQ wq, Rest&&... r) { return wq->add(std::bind(std::forward<Rest>(r)...)); } +/// **Experimental** template <class WQ, class... Rest> void schedule_work(WQ wq, duration d, Rest&&... r) { wq->schedule(d, std::bind(std::forward<Rest>(r)...)); } +/// **Experimental** template <class... Rest> work make_work(Rest&&... r) { return std::bind(std::forward<Rest>(r)...); } + #endif } // proton --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org For additional commands, e-mail: commits-h...@qpid.apache.org
