Return-Path: X-Original-To: archive-asf-public-internal@cust-asf2.ponee.io Delivered-To: archive-asf-public-internal@cust-asf2.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by cust-asf2.ponee.io (Postfix) with ESMTP id DD7D7200CE1 for ; Thu, 31 Aug 2017 14:27:06 +0200 (CEST) Received: by cust-asf.ponee.io (Postfix) id DBE8D16B078; Thu, 31 Aug 2017 12:27:06 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 5966516B075 for ; Thu, 31 Aug 2017 14:27:05 +0200 (CEST) Received: (qmail 93189 invoked by uid 500); 31 Aug 2017 12:27:02 -0000 Mailing-List: contact commits-help@qpid.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@qpid.apache.org Delivered-To: mailing list commits@qpid.apache.org Received: (qmail 93180 invoked by uid 99); 31 Aug 2017 12:27:02 -0000 Received: from git1-us-west.apache.org (HELO git1-us-west.apache.org) (140.211.11.23) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 31 Aug 2017 12:27:02 +0000 Received: by git1-us-west.apache.org (ASF Mail Server at git1-us-west.apache.org, from userid 33) id 10465F32F1; Thu, 31 Aug 2017 12:27:01 +0000 (UTC) Content-Type: text/plain; charset="us-ascii" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit From: jross@apache.org To: commits@qpid.apache.org Message-Id: X-Mailer: ASF-Git Admin Mailer Subject: qpid-proton git commit: PROTON-1543: Various improvements to the C++ API docs Date: Thu, 31 Aug 2017 12:27:01 +0000 (UTC) archived-at: Thu, 31 Aug 2017 12:27:07 -0000 Repository: qpid-proton Updated Branches: refs/heads/master ba696d242 -> b60f093a1 PROTON-1543: Various improvements to the C++ API docs - Use 'Unsettled API' instead of 'Experimental' - Improve the map API docs - Document default values for endpoint options Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/b60f093a Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/b60f093a Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/b60f093a Branch: refs/heads/master Commit: b60f093a1ca77f7d2de94fdac3a57b16a3765426 Parents: ba696d2 Author: Justin Ross Authored: Thu Aug 31 05:25:08 2017 -0700 Committer: Justin Ross Committed: Thu Aug 31 05:25:08 2017 -0700 ---------------------------------------------------------------------- proton-c/bindings/cpp/docs/io.md | 2 +- .../cpp/include/proton/codec/common.hpp | 4 +- .../cpp/include/proton/codec/decoder.hpp | 2 +- .../cpp/include/proton/codec/encoder.hpp | 2 +- .../cpp/include/proton/connection_options.hpp | 31 ++++--- .../bindings/cpp/include/proton/container.hpp | 4 +- .../cpp/include/proton/error_condition.hpp | 2 +- .../cpp/include/proton/internal/data.hpp | 2 +- .../cpp/include/proton/io/connection_driver.hpp | 6 +- .../cpp/include/proton/io/link_namer.hpp | 4 +- proton-c/bindings/cpp/include/proton/link.hpp | 2 +- .../cpp/include/proton/listen_handler.hpp | 2 +- proton-c/bindings/cpp/include/proton/map.hpp | 85 ++++++++++++-------- .../bindings/cpp/include/proton/message.hpp | 12 +-- .../cpp/include/proton/messaging_handler.hpp | 4 +- .../bindings/cpp/include/proton/namespaces.hpp | 4 +- .../bindings/cpp/include/proton/receiver.hpp | 2 +- .../cpp/include/proton/receiver_options.hpp | 34 ++++---- proton-c/bindings/cpp/include/proton/sender.hpp | 2 +- .../cpp/include/proton/sender_options.hpp | 11 ++- .../cpp/include/proton/session_options.hpp | 4 +- proton-c/bindings/cpp/include/proton/source.hpp | 4 +- .../cpp/include/proton/source_options.hpp | 23 +++--- proton-c/bindings/cpp/include/proton/ssl.hpp | 6 +- proton-c/bindings/cpp/include/proton/symbol.hpp | 8 +- .../cpp/include/proton/target_options.hpp | 17 ++-- proton-c/bindings/cpp/include/proton/url.hpp | 2 +- .../bindings/cpp/include/proton/work_queue.hpp | 24 +++--- 28 files changed, 169 insertions(+), 136 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/docs/io.md ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/docs/io.md b/proton-c/bindings/cpp/docs/io.md index c0f7b02..2f380ce 100644 --- a/proton-c/bindings/cpp/docs/io.md +++ b/proton-c/bindings/cpp/docs/io.md @@ -1,6 +1,6 @@ # IO integration {#io_page} -**Experimental** - The `proton::io` interfaces are new and remain +**Unsettled API** - The `proton::io` interfaces are new and remain subject to change. The `proton::io` namespace contains a service provider interface (SPI) http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/codec/common.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/common.hpp b/proton-c/bindings/cpp/include/proton/codec/common.hpp index e8d8ce5..61de8a5 100644 --- a/proton-c/bindings/cpp/include/proton/codec/common.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/common.hpp @@ -27,7 +27,7 @@ namespace proton { namespace codec { -/// **Experimental** - Start encoding a complex type. +/// **Unsettled API** - Start encoding a complex type. struct start { /// @cond INTERNAL /// XXX Document @@ -50,7 +50,7 @@ struct start { /// @endcond }; -/// **Experimental** - Finish inserting or extracting a complex type. +/// **Unsettled API** - Finish inserting or extracting a complex type. struct finish {}; } // codec http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp b/proton-c/bindings/cpp/include/proton/codec/decoder.hpp index 3dc6d57..cf42f90 100644 --- a/proton-c/bindings/cpp/include/proton/codec/decoder.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/decoder.hpp @@ -44,7 +44,7 @@ class value_base; namespace codec { -/// **Experimental** - Stream-like decoder from AMQP bytes to C++ +/// **Unsettled API** - Stream-like decoder from AMQP bytes to C++ /// values. /// /// For internal use only. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp b/proton-c/bindings/cpp/include/proton/codec/encoder.hpp index 2610021..043e999 100644 --- a/proton-c/bindings/cpp/include/proton/codec/encoder.hpp +++ b/proton-c/bindings/cpp/include/proton/codec/encoder.hpp @@ -38,7 +38,7 @@ class value_base; namespace codec { -/// **Experimental** - Stream-like encoder from C++ values to AMQP +/// **Unsettled API** - Stream-like encoder from C++ values to AMQP /// bytes. /// /// For internal use only. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 c0ff457..62af5f3 100644 --- a/proton-c/bindings/cpp/include/proton/connection_options.hpp +++ b/proton-c/bindings/cpp/include/proton/connection_options.hpp @@ -86,26 +86,26 @@ class connection_options { /// 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. The default value is 32767. + /// Set the maximum number of open sessions. The default is 32767. PN_CPP_EXTERN connection_options& max_sessions(uint16_t max); - /// Set the idle timeout. By default, none is set. + /// Set the idle timeout. The default is no timeout. /// - /// 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 + /// If set, the local peer will disconnect if it receives no AMQP + /// frames for an interval longer than `duration`. Also known as + /// "heartbeating", this is 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); - /// 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. For server connections, it is not set by - /// default. + /// Set the virtual host name for the connection. For client + /// connections, it defaults to the host name used to set up the + /// connection. For server connections, it is unset by default. + /// + /// If making a client connection by SSL/TLS, this name is also + /// used for certificate verification and Server Name Indication. PN_CPP_EXTERN connection_options& virtual_host(const std::string& name); /// Set the user name used to authenticate the connection. It is @@ -117,8 +117,7 @@ class connection_options { /// 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. + /// Set the password used to authenticate the connection. /// /// This value is ignored if the connection is created by /// container::listen. @@ -140,7 +139,7 @@ class connection_options { /// Enable or disable SASL. PN_CPP_EXTERN connection_options& sasl_enabled(bool); - /// Force the enabling of SASL mechanisms that disclose clear text + /// Force the enabling of SASL mechanisms that disclose cleartext /// passwords over the connection. By default, such mechanisms /// are disabled. PN_CPP_EXTERN connection_options& sasl_allow_insecure_mechs(bool); @@ -148,10 +147,10 @@ class connection_options { /// Specify the allowed mechanisms for use on the connection. PN_CPP_EXTERN connection_options& sasl_allowed_mechs(const std::string&); - /// **Experimental** - Set the SASL configuration name. + /// **Unsettled API** - Set the SASL configuration name. PN_CPP_EXTERN connection_options& sasl_config_name(const std::string&); - /// **Experimental** - Set the SASL configuration path. + /// **Unsettled API** - Set the SASL configuration path. PN_CPP_EXTERN connection_options& sasl_config_path(const std::string&); /// Update option values from values set in other. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 64e52ad..d447abe 100644 --- a/proton-c/bindings/cpp/include/proton/container.hpp +++ b/proton-c/bindings/cpp/include/proton/container.hpp @@ -124,7 +124,7 @@ class PN_CPP_CLASS_EXTERN container { /// auto_stop is set by default when a new container is created. PN_CPP_EXTERN void auto_stop(bool); - /// **Experimental** - Stop the container with an error_condition + /// **Unsettled API** - Stop the container with an error_condition /// err. /// /// - Abort all open connections and listeners. @@ -133,7 +133,7 @@ class PN_CPP_CLASS_EXTERN container { /// - run() will return in all threads. PN_CPP_EXTERN void stop(const error_condition& err); - /// **Experimental** - Stop the container with an empty error + /// **Unsettled API** - Stop the container with an empty error /// condition. /// /// @see stop(const error_condition&) http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/error_condition.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/error_condition.hpp b/proton-c/bindings/cpp/include/proton/error_condition.hpp index fb0d461..159356e 100644 --- a/proton-c/bindings/cpp/include/proton/error_condition.hpp +++ b/proton-c/bindings/cpp/include/proton/error_condition.hpp @@ -50,7 +50,7 @@ class error_condition { /// Create an error condition with a name and description. PN_CPP_EXTERN error_condition(std::string name, std::string description); - /// **Experimental** - Create an error condition with name, + /// **Unsettled API** - Create an error condition with name, /// description, and informational properties. PN_CPP_EXTERN error_condition(std::string name, std::string description, proton::value properties); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/internal/data.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/internal/data.hpp b/proton-c/bindings/cpp/include/proton/internal/data.hpp index 0e35486..97f900a 100644 --- a/proton-c/bindings/cpp/include/proton/internal/data.hpp +++ b/proton-c/bindings/cpp/include/proton/internal/data.hpp @@ -78,7 +78,7 @@ class data : public object { }; /// @endcond -/// **Experimental** - Save and restore codec state +/// **Unsettled API** - Save and restore codec state /// /// A state_guard saves the state and restores it in the destructor /// unless cancel() is called. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp b/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp index f9774ac..a7e96fe 100644 --- a/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp +++ b/proton-c/bindings/cpp/include/proton/io/connection_driver.hpp @@ -39,7 +39,7 @@ class proton_handler; namespace io { -/// **Experimental** - Pointer to a mutable memory region with a size. +/// **Unsettled API** - Pointer to a mutable memory region with a size. struct mutable_buffer { char* data; ///< Beginning of the buffered data. size_t size; ///< Number of bytes in the buffer. @@ -48,7 +48,7 @@ struct mutable_buffer { mutable_buffer(char* data_=0, size_t size_=0) : data(data_), size(size_) {} }; -/// **Experimental** - Pointer to a const memory region with a size. +/// **Unsettled API** - Pointer to a const memory region with a size. struct const_buffer { const char* data; ///< Beginning of the buffered data. size_t size; ///< Number of bytes in the buffer. @@ -57,7 +57,7 @@ struct const_buffer { const_buffer(const char* data_=0, size_t size_=0) : data(data_), size(size_) {} }; -/// **Experimental** - An AMQP driver for a single connection. +/// **Unsettled API** - An AMQP driver for a single connection. /// /// io::connection_driver manages a single proton::connection and dispatches /// events to a proton::messaging_handler. It does no IO of its own, but allows you to http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/io/link_namer.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/io/link_namer.hpp b/proton-c/bindings/cpp/include/proton/io/link_namer.hpp index a0eea67..e6d84ee 100644 --- a/proton-c/bindings/cpp/include/proton/io/link_namer.hpp +++ b/proton-c/bindings/cpp/include/proton/io/link_namer.hpp @@ -31,7 +31,7 @@ class connection; namespace io { -/// **Experimental** - Generate default link names that are unique +/// **Unsettled API** - Generate default link names that are unique /// within a container. base_container provides a default /// implementation. class link_namer { @@ -42,7 +42,7 @@ class link_namer { virtual std::string link_name() = 0; }; -/// *Experimental* - Set the link_namer to use on a connection. +/// **Unsettled API** - Set the link_namer to use on a connection. PN_CPP_EXTERN void set_link_namer(connection&, link_namer&); } // io http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/link.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/link.hpp b/proton-c/bindings/cpp/include/proton/link.hpp index 8627ec9..eb28613 100644 --- a/proton-c/bindings/cpp/include/proton/link.hpp +++ b/proton-c/bindings/cpp/include/proton/link.hpp @@ -64,7 +64,7 @@ PN_CPP_CLASS_EXTERN link : public internal::object , public endpoint /// Credit available on the link. PN_CPP_EXTERN int credit() const; - /// **Experimental** - True for a receiver if a drain cycle has + /// **Unsettled API** - True for a receiver if a drain cycle has /// been started and the corresponding `on_receiver_drain_finish` /// event is still pending. True for a sender if the receiver has /// requested a drain of credit and the sender has unused credit. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/listen_handler.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/listen_handler.hpp b/proton-c/bindings/cpp/include/proton/listen_handler.hpp index 08d5e76..5373c54 100644 --- a/proton-c/bindings/cpp/include/proton/listen_handler.hpp +++ b/proton-c/bindings/cpp/include/proton/listen_handler.hpp @@ -27,7 +27,7 @@ namespace proton { // XXX Discuss more -/// **Experimental** - A handler for incoming connections. +/// **Unsettled API** - A handler for incoming connections. /// /// Implement this interface and pass to proton::container::listen() /// to be notified of new connections. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/map.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/map.hpp b/proton-c/bindings/cpp/include/proton/map.hpp index 86948e5..dade948 100644 --- a/proton-c/bindings/cpp/include/proton/map.hpp +++ b/proton-c/bindings/cpp/include/proton/map.hpp @@ -1,5 +1,5 @@ -#ifndef PROTON_CPP_MAP_H -#define PROTON_CPP_MAP_H +#ifndef PROTON_MAP_HPP +#define PROTON_MAP_HPP /* * @@ -23,8 +23,7 @@ */ #include "./value.hpp" - -#include "internal/pn_unique_ptr.hpp" +#include "./internal/pn_unique_ptr.hpp" #include @@ -51,14 +50,16 @@ PN_CPP_EXTERN proton::codec::encoder& operator<<(proton::codec::encoder& e, cons template PN_CPP_EXTERN void swap(map&, map&); -/// Used to access standard AMQP property, annotation and filter maps attached -/// to proton::message and proton::source. +/// A collection of key-value pairs. /// -/// Provides only basic get()/set() operations for convenience. For more -/// complicated use (iteration, preserving order etc.) you should convert to a -/// standard C++ map type such as std::map. See @ref message_properties.cpp -/// and @ref types_page. +/// Used to access standard AMQP property, annotation, and filter maps +/// attached to proton::message and proton::source. /// +/// This class provides only basic get() and put() operations for +/// convenience. For more complicated uses (iteration, preserving +/// order, and so on), convert the value to a standard C++ map type +/// such as `std::map`. See @ref message_properties.cpp and @ref +/// types_page. template class PN_CPP_CLASS_EXTERN map { template @@ -66,50 +67,69 @@ class PN_CPP_CLASS_EXTERN map { public internal::enable_if::value, U> {}; public: - /// @name Construct and assign - /// @{ + /// Construct an empty map. PN_CPP_EXTERN map(); - PN_CPP_EXTERN map(const map& cm); - PN_CPP_EXTERN map& operator=(const map& cm); + + /// Copy a map. + PN_CPP_EXTERN map(const map&); + + /// Copy a map. + PN_CPP_EXTERN map& operator=(const map&); + #if PN_CPP_HAS_RVALUE_REFERENCES + /// Move a map. PN_CPP_EXTERN map(map&&); + + /// Move a map. PN_CPP_EXTERN map& operator=(map&&); #endif - ///@} PN_CPP_EXTERN ~map(); - /// Type-safe assign from a compatible map, e.g. std::map - see @ref types_page + /// Type-safe assign from a compatible map, for instance + /// `std::map`. See @ref types_page. template - typename assignable_map::type operator=(const M& x) { value(x); return *this;} + typename assignable_map::type operator=(const M& x) { value(x); return *this; } /// Copy from a proton::value. - /// @throw proton::conversion_error if x does not contain a compatible map. + /// + /// @throw proton::conversion_error if `x` does not contain a + /// compatible map. PN_CPP_EXTERN void value(const value& x); - /// Access as a proton::value containing an AMQP map + + /// Access as a proton::value containing an AMQP map. PN_CPP_EXTERN proton::value& value(); - /// Access as a proton::value containing an AMQP map + + /// Access as a proton::value containing an AMQP map. PN_CPP_EXTERN const proton::value& value() const; - /// Get the map entry for key k, return T() if no such entry + /// Get the map entry for key `k`. Return `T()` if there is no + /// such entry. PN_CPP_EXTERN T get(const K& k) const; - /// Put a map entry for key k. + + /// Put a map entry for key `k`. PN_CPP_EXTERN void put(const K& k, const T& v); - /// Erase the map entry at k + + /// Erase the map entry at `k`. PN_CPP_EXTERN size_t erase(const K& k); - /// True if there is a map entry for k + + /// True if the map has an entry for `k`. PN_CPP_EXTERN bool exists(const K& k) const; - /// Number of map entries + + /// Get the number of map entries. PN_CPP_EXTERN size_t size() const; - /// Clear the map + + /// Remove all map entries. PN_CPP_EXTERN void clear(); - /// True if the map is empty + + /// True if the map has no entries. PN_CPP_EXTERN bool empty() const; - ///@cond INTERNAL + /// @cond INTERNAL explicit map(pn_data_t*); void reset(pn_data_t*); + /// @endcond - private: + private: typedef map_type_impl map_type; mutable internal::pn_unique_ptr map_; mutable proton::value value_; @@ -117,12 +137,13 @@ class PN_CPP_CLASS_EXTERN map { map_type& cache() const; proton::value& flush() const; + /// @cond INTERNAL friend PN_CPP_EXTERN proton::codec::decoder& operator>> <>(proton::codec::decoder&, map&); friend PN_CPP_EXTERN proton::codec::encoder& operator<< <>(proton::codec::encoder&, const map&); friend PN_CPP_EXTERN void swap<>(map&, map&); - /// @endcond + /// @endcond }; -} // namespace proton +} // proton -#endif // PROTON_CPP_MAP_H +#endif // PROTON_MAP_HPP http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/message.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/message.hpp b/proton-c/bindings/cpp/include/proton/message.hpp index a428c46..40aa98c 100644 --- a/proton-c/bindings/cpp/include/proton/message.hpp +++ b/proton-c/bindings/cpp/include/proton/message.hpp @@ -46,11 +46,11 @@ namespace proton { /// message. class message { public: - /// **Experimental** - A map of string keys and AMQP scalar + /// **Unsettled API** - A map of string keys and AMQP scalar /// values. typedef map property_map; - /// **Experimental** - A map of AMQP annotation keys and AMQP + /// **Unsettled API** - A map of AMQP annotation keys and AMQP /// values. typedef map annotation_map; @@ -287,17 +287,17 @@ class message { /// @} - /// @name **Experimental** - Application properties + /// @name **Unsettled API** - Application properties /// @{ - /// **Experimental** - Get the application properties map. It can + /// **Unsettled API** - Get the application properties map. It can /// be modified in place. PN_CPP_EXTERN property_map& properties(); - /// **Experimental** - examine the application properties map. + /// **Unsettled API** - examine the application properties map. PN_CPP_EXTERN const property_map& properties() const; - /// @name **Experimental** - Annotations + /// @name **Unsettled API** - Annotations /// /// Normally used by messaging infrastructure, not applications. /// @{ http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp index a5e2bdd..9c4d8f8 100644 --- a/proton-c/bindings/cpp/include/proton/messaging_handler.hpp +++ b/proton-c/bindings/cpp/include/proton/messaging_handler.hpp @@ -143,11 +143,11 @@ PN_CPP_CLASS_EXTERN messaging_handler { /// The sending peer settled a transfer. PN_CPP_EXTERN virtual void on_delivery_settle(delivery &d); - /// **Experimental** - The receiving peer has requested a drain of + /// **Unsettled API** - The receiving peer has requested a drain of /// remaining credit. PN_CPP_EXTERN virtual void on_sender_drain_start(sender &s); - /// **Experimental** - The credit outstanding at the time of the + /// **Unsettled API** - The credit outstanding at the time of the /// call to receiver::drain has been consumed or returned. PN_CPP_EXTERN virtual void on_receiver_drain_finish(receiver &r); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/namespaces.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/namespaces.hpp b/proton-c/bindings/cpp/include/proton/namespaces.hpp index 62b4913..d7b5cf9 100644 --- a/proton-c/bindings/cpp/include/proton/namespaces.hpp +++ b/proton-c/bindings/cpp/include/proton/namespaces.hpp @@ -23,7 +23,7 @@ /// The main Proton namespace. namespace proton { -/// **Experimental** - AMQP data encoding and decoding. +/// **Unsettled API** - AMQP data encoding and decoding. /// /// You can use these classes on an experimental basis to create your /// own AMQP encodings for C++ types, but they may change in the @@ -32,7 +32,7 @@ namespace proton { namespace codec { } -/// **Experimental** - An SPI for multithreaded network IO. +/// **Unsettled API** - An SPI for multithreaded network IO. namespace io { } http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/receiver.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/receiver.hpp b/proton-c/bindings/cpp/include/proton/receiver.hpp index b995e6f..46e5c4d 100644 --- a/proton-c/bindings/cpp/include/proton/receiver.hpp +++ b/proton-c/bindings/cpp/include/proton/receiver.hpp @@ -63,7 +63,7 @@ PN_CPP_CLASS_EXTERN receiver : public link { /// the drain completes. PN_CPP_EXTERN void add_credit(uint32_t); - /// **Experimental** - Commence a drain cycle. If there is + /// **Unsettled API** - Commence a drain cycle. If there is /// positive credit, a request is sent to the sender to /// immediately use up all of the existing credit balance by /// sending messages that are immediately available and releasing http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/receiver_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/receiver_options.hpp b/proton-c/bindings/cpp/include/proton/receiver_options.hpp index 413e4d4..1e43adb 100644 --- a/proton-c/bindings/cpp/include/proton/receiver_options.hpp +++ b/proton-c/bindings/cpp/include/proton/receiver_options.hpp @@ -62,42 +62,46 @@ class receiver_options { /// Copy options. PN_CPP_EXTERN receiver_options& operator=(const receiver_options&); - /// Merge with another option set + /// Merge with another option set. PN_CPP_EXTERN void update(const receiver_options& other); - /// Set a messaging_handler for receiver events only. - /// The handler is no longer in use when messaging_handler::on_receiver_close() is called. + /// Set a messaging_handler for receiver events only. The handler + /// is no longer in use when + /// messaging_handler::on_receiver_close() is called. PN_CPP_EXTERN receiver_options& handler(class messaging_handler&); - /// Set the delivery mode on the receiver. + /// Set the delivery mode on the receiver. The default is + /// delivery_mode::AT_LEAST_ONCE. PN_CPP_EXTERN receiver_options& delivery_mode(delivery_mode); - /// Automatically accept inbound messages that aren't otherwise - /// released, rejected, or modified (default is true). + /// Enable or disable automatic acceptance of messages that aren't + /// otherwise released, rejected, or modified. It is enabled by + /// default. PN_CPP_EXTERN receiver_options& auto_accept(bool); - /// Automatically settle messages (default is true). + /// Enable or disable automatic settlement of messages. It is + /// enabled by default. PN_CPP_EXTERN receiver_options& auto_settle(bool); /// Options for the source node of the receiver. - PN_CPP_EXTERN receiver_options& source(source_options &); + PN_CPP_EXTERN receiver_options& source(source_options&); /// Options for the target node of the receiver. - PN_CPP_EXTERN receiver_options& target(target_options &); + PN_CPP_EXTERN receiver_options& target(target_options&); - /// Set automated flow control to pre-fetch this many messages - /// (default is 10). Set to zero to disable automatic credit - /// replenishing. - PN_CPP_EXTERN receiver_options& credit_window(int); + /// Automatically replenish credit for flow control up to `count` + /// messages. The default is 10. Set to zero to disable + /// automatic replenishment. + PN_CPP_EXTERN receiver_options& credit_window(int count); - /// @cond INTERNAL private: void apply(receiver &) const; class impl; internal::pn_unique_ptr impl_; - friend class receiver; + /// @cond INTERNAL + friend class receiver; /// @endcond }; http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/sender.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/sender.hpp b/proton-c/bindings/cpp/include/proton/sender.hpp index b01f21c..7a1ae15 100644 --- a/proton-c/bindings/cpp/include/proton/sender.hpp +++ b/proton-c/bindings/cpp/include/proton/sender.hpp @@ -60,7 +60,7 @@ PN_CPP_CLASS_EXTERN sender : public link { /// Get the target node. PN_CPP_EXTERN class target target() const; - /// **Experimental** - Return all unused credit to the receiver in + /// **Unsettled API** - Return all unused credit to the receiver in /// response to a drain request. Has no effect unless there has /// been a drain request and there is remaining credit to use or /// return. http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/sender_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/sender_options.hpp b/proton-c/bindings/cpp/include/proton/sender_options.hpp index 9d7bb42..ea7f7d3 100644 --- a/proton-c/bindings/cpp/include/proton/sender_options.hpp +++ b/proton-c/bindings/cpp/include/proton/sender_options.hpp @@ -43,14 +43,13 @@ namespace proton { /// /// @code /// sender_options opts; -/// opts.browsing(true); +/// opts.delivery_mode(delivery_mode::AT_MOST_ONCE); /// l1 = container.open_sender(url1, opts.handler(h1)); /// c2 = container.open_receiver(url2, opts.handler(h2)); /// @endcode /// /// Normal value semantics: copy or assign creates a separate copy of /// the options. -// XXX opts.browsing is not a good example here class sender_options { public: /// Create an empty set of options. @@ -80,19 +79,19 @@ class sender_options { PN_CPP_EXTERN sender_options& auto_settle(bool); /// Options for the source node of the sender. - PN_CPP_EXTERN sender_options& source(const source_options &); + PN_CPP_EXTERN sender_options& source(const source_options&); /// Options for the receiver node of the receiver. - PN_CPP_EXTERN sender_options& target(const target_options &); + PN_CPP_EXTERN sender_options& target(const target_options&); - /// @cond INTERNAL private: void apply(sender&) const; class impl; internal::pn_unique_ptr impl_; - friend class sender; + /// @cond INTERNAL + friend class sender; /// @endcond }; http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/session_options.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/session_options.hpp b/proton-c/bindings/cpp/include/proton/session_options.hpp index eb47a89..9672c82 100644 --- a/proton-c/bindings/cpp/include/proton/session_options.hpp +++ b/proton-c/bindings/cpp/include/proton/session_options.hpp @@ -34,7 +34,6 @@ namespace proton { /// /// Normal value semantics: copy or assign creates a separate copy of /// the options. -// XXX Does this need the CLASS_EXTERN stuff? - Add just for consistency class session_options { public: /// Create an empty set of options. @@ -51,8 +50,9 @@ class session_options { /// Set a messaging_handler for the session. PN_CPP_EXTERN session_options& handler(class messaging_handler &); - /// @cond INTERNAL // Other useful session configuration TBD. + + /// @cond INTERNAL private: void apply(session&) const; http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/source.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/source.hpp b/proton-c/bindings/cpp/include/proton/source.hpp index 59963dd..52afd8f 100644 --- a/proton-c/bindings/cpp/include/proton/source.hpp +++ b/proton-c/bindings/cpp/include/proton/source.hpp @@ -40,7 +40,7 @@ namespace proton { /// @see proton::sender, proton::receiver, proton::target class source : public terminus { public: - /// **Experimental** - A map of AMQP symbol keys and filter + /// **Unsettled API** - A map of AMQP symbol keys and filter /// specifiers. typedef map filter_map; @@ -68,7 +68,7 @@ class source : public terminus { /// Get the distribution mode. PN_CPP_EXTERN enum distribution_mode distribution_mode() const; - /// **Experimental** - Obtain the set of message filters. + /// **Unsettled API** - Obtain the set of message filters. PN_CPP_EXTERN const filter_map& filters() const; private: http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 19e3cdf..1b2876c 100644 --- a/proton-c/bindings/cpp/include/proton/source_options.hpp +++ b/proton-c/bindings/cpp/include/proton/source_options.hpp @@ -40,7 +40,6 @@ namespace proton { /// the options. class source_options { public: - /// Create an empty set of options. PN_CPP_EXTERN source_options(); @@ -52,26 +51,32 @@ class source_options { /// Copy options. PN_CPP_EXTERN source_options& operator=(const source_options&); - /// Set the address for the source. Ignored if dynamic is true. + /// Set the address for the source. It is unset by default. The + /// address is ignored if dynamic() is true. PN_CPP_EXTERN source_options& address(const std::string&); - /// Request a dynamically created node to be created by the remote peer. - /// Any specified source address is ignored. + /// Request that a node be dynamically created by the remote peer. + /// The default is false. Any specified source address() is + /// ignored. PN_CPP_EXTERN source_options& dynamic(bool); - /// Control whether messsages are browsed or consumed. + /// Control whether messsages are browsed or consumed. The + /// default is source::MOVE, meaning consumed. PN_CPP_EXTERN source_options& distribution_mode(enum source::distribution_mode); - /// Control the persistence of source state. + /// Control the persistence of the source node. The default is + /// source::NONDURABLE, meaning non-persistent. PN_CPP_EXTERN source_options& durability_mode(enum source::durability_mode); - /// The expiry period after which the source is discarded. + /// The expiry period after which the source is discarded. The + /// default is no timeout. PN_CPP_EXTERN source_options& timeout(duration); - /// Control when the clock for expiration begins. + /// Control when the clock for expiration begins. The default is + /// source::LINK_CLOSE. PN_CPP_EXTERN source_options& expiry_policy(enum source::expiry_policy); - /// **Experimental** - Specify a filter mechanism on the source + /// **Unsettled API** - Specify a filter mechanism on the source /// that restricts message flow to a subset of the available /// messages. PN_CPP_EXTERN source_options& filters(const source::filter_map&); http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/ssl.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/ssl.hpp b/proton-c/bindings/cpp/include/proton/ssl.hpp index c6c4c93..896c23d 100644 --- a/proton-c/bindings/cpp/include/proton/ssl.hpp +++ b/proton-c/bindings/cpp/include/proton/ssl.hpp @@ -92,7 +92,7 @@ class ssl { /// @endcond }; -/// **Experimental** - An SSL certificate. +/// **Unsettled API** - An SSL certificate. class ssl_certificate { public: /// Create an SSL certificate. @@ -141,7 +141,7 @@ class ssl_domain { } -/// **Experimental** - SSL configuration for inbound connections. +/// **Unsettled API** - SSL configuration for inbound connections. class ssl_server_options : private internal::ssl_domain { public: /// Server SSL options based on the supplied X.509 certificate @@ -168,7 +168,7 @@ class ssl_server_options : private internal::ssl_domain { /// @endcond }; -/// **Experimental** - SSL configuration for outbound connections. +/// **Unsettled API** - SSL configuration for outbound connections. class ssl_client_options : private internal::ssl_domain { public: /// Create SSL client options (no client certificate). http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/symbol.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/symbol.hpp b/proton-c/bindings/cpp/include/proton/symbol.hpp index 303f350..3f60540 100644 --- a/proton-c/bindings/cpp/include/proton/symbol.hpp +++ b/proton-c/bindings/cpp/include/proton/symbol.hpp @@ -26,18 +26,18 @@ namespace proton { -/// A std::string that represents the AMQP symbol type. +/// A `std::string` that represents the AMQP symbol type. /// -/// A symbol can only contain 7-bit ASCII characters. +/// A symbol can contain only 7-bit ASCII characters. class symbol : public std::string { public: - /// Construct from a std::string. + /// Construct from a `std::string`. symbol(const std::string& s=std::string()) : std::string(s) {} /// Construct from a C string. symbol(const char* s) : std::string(s) {} - /// Construct from any sequence of char. + /// Construct from any sequence of `char`. template symbol(Iter start, Iter finish) : std::string(start, finish) {} }; http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 0f2245b..05249d0 100644 --- a/proton-c/bindings/cpp/include/proton/target_options.hpp +++ b/proton-c/bindings/cpp/include/proton/target_options.hpp @@ -51,20 +51,25 @@ class target_options { /// Copy options. PN_CPP_EXTERN target_options& operator=(const target_options&); - /// Set the address for the target. Ignored if dynamic is true. + /// Set the address for the target. It is unset by default. The + /// address is ignored if dynamic() is true. PN_CPP_EXTERN target_options& address(const std::string& addr); - /// Request a dynamically created node to be created by the peer. - /// Any specified target address is ignored. + /// Request that a node be dynamically created by the remote peer. + /// The default is false. Any specified target address() is + /// ignored. PN_CPP_EXTERN target_options& dynamic(bool); - /// Control the persistence of target state. + /// Control the persistence of the target node. The default is + /// target::NONDURABLE, meaning non-persistent. PN_CPP_EXTERN target_options& durability_mode(enum target::durability_mode); - /// The expiry period after which the target is discarded. + /// The expiry period after which the target is discarded. The + /// default is no timeout. PN_CPP_EXTERN target_options& timeout(duration); - /// Control when the clock for expiration begins. + /// Control when the clock for expiration begins. The default is + /// target::LINK_CLOSE. PN_CPP_EXTERN target_options& expiry_policy(enum target::expiry_policy); private: http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/proton-c/bindings/cpp/include/proton/url.hpp ---------------------------------------------------------------------- diff --git a/proton-c/bindings/cpp/include/proton/url.hpp b/proton-c/bindings/cpp/include/proton/url.hpp index b94b24d..28f31e9 100644 --- a/proton-c/bindings/cpp/include/proton/url.hpp +++ b/proton-c/bindings/cpp/include/proton/url.hpp @@ -70,7 +70,7 @@ class url { /// @cond INTERNAL /// XXX I want to understand why this is important to keep. /// - /// **Experimental** - Parse `url_str` as an AMQP URL. If + /// **Unsettled API** - Parse `url_str` as an AMQP URL. If /// `defaults` is true, fill in defaults for missing values. /// Otherwise, return an empty string for missing values. /// http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/b60f093a/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 2d728fd..f5e60cd 100644 --- a/proton-c/bindings/cpp/include/proton/work_queue.hpp +++ b/proton-c/bindings/cpp/include/proton/work_queue.hpp @@ -37,21 +37,21 @@ struct pn_link_t; namespace proton { -/// **Experimental** - Work to be queued on a @ref work_queue. It can +/// **Unsettled API** - 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** + /// **Unsettled API** work(void_function0& f): item_( [&f]() { f(); }) {} - /// **Experimental** - Construct a unit of work from a + /// **Unsettled API** - Construct a unit of work from a /// std::function. template work(T f): item_(f) {} - /// **Experimental** + /// **Unsettled API** void operator()() { item_(); } #else /// **Experimetnal** @@ -71,7 +71,7 @@ class work { #endif }; -/// **Experimental** - A work queue for serial execution. +/// **Unsettled API** - A work queue for serial execution. /// /// Event handler functions associated with a single /// proton::connection are called in sequence. The connection's @@ -94,15 +94,15 @@ class PN_CPP_CLASS_EXTERN work_queue { /// @endcond public: - /// **Experimental** - Create a work_queue. + /// **Unsettled API** - Create a work_queue. PN_CPP_EXTERN work_queue(); - /// **Experimental** - Create a work_queue backed by `container`. + /// **Unsettled API** - Create a work_queue backed by `container`. PN_CPP_EXTERN work_queue(container&); PN_CPP_EXTERN ~work_queue(); - /// **Experimental** - Add work to the work queue: f() will be + /// **Unsettled API** - Add work to the work queue: f() will be /// called serialised with other work in the queue: deferred and /// possibly in another thread. /// @@ -110,7 +110,7 @@ class PN_CPP_CLASS_EXTERN work_queue { /// or f() cannot be injected for any other reason. PN_CPP_EXTERN bool add(work f); - /// **Experimental** - Add work to the work queue after duration: + /// **Unsettled API** - 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. /// @@ -363,19 +363,19 @@ 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** +/// **Unsettled API** template bool schedule_work(WQ wq, Rest&&... r) { return wq->add(std::bind(std::forward(r)...)); } -/// **Experimental** +/// **Unsettled API** template void schedule_work(WQ wq, duration d, Rest&&... r) { wq->schedule(d, std::bind(std::forward(r)...)); } -/// **Experimental** +/// **Unsettled API** template work make_work(Rest&&... r) { return std::bind(std::forward(r)...); --------------------------------------------------------------------- To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org For additional commands, e-mail: commits-help@qpid.apache.org