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/01 15:04:12 UTC
[44/50] qpid-proton git commit: PROTON-1543: Various improvements to
the C++ API docs
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/go1
Commit: b60f093a1ca77f7d2de94fdac3a57b16a3765426
Parents: ba696d2
Author: Justin Ross <jr...@apache.org>
Authored: Thu Aug 31 05:25:08 2017 -0700
Committer: Justin Ross <jr...@apache.org>
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<pn_data_t> {
};
/// @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<pn_link_t> , 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 <cstddef>
@@ -51,14 +50,16 @@ PN_CPP_EXTERN proton::codec::encoder& operator<<(proton::codec::encoder& e, cons
template <class K, class T>
PN_CPP_EXTERN void swap(map<K,T>&, map<K,T>&);
-/// 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 K, class T>
class PN_CPP_CLASS_EXTERN map {
template <class M, class U=void>
@@ -66,50 +67,69 @@ class PN_CPP_CLASS_EXTERN map {
public internal::enable_if<codec::is_encodable_map<M,K,T>::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<K,T> - see @ref types_page
+ /// Type-safe assign from a compatible map, for instance
+ /// `std::map<K,T>`. See @ref types_page.
template <class M>
- typename assignable_map<M, map&>::type operator=(const M& x) { value(x); return *this;}
+ typename assignable_map<M, 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<K,T> map_type;
mutable internal::pn_unique_ptr<map_type> 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<std::string, scalar> 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_key, value> 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> 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> 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<symbol, value> 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<class Iter> 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 <class T>
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 <class WQ, class... Rest>
bool schedule_work(WQ wq, Rest&&... r) {
return wq->add(std::bind(std::forward<Rest>(r)...));
}
-/// **Experimental**
+/// **Unsettled API**
template <class WQ, class... Rest>
void schedule_work(WQ wq, duration d, Rest&&... r) {
wq->schedule(d, std::bind(std::forward<Rest>(r)...));
}
-/// **Experimental**
+/// **Unsettled API**
template <class... Rest>
work make_work(Rest&&... r) {
return std::bind(std::forward<Rest>(r)...);
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org