You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@qpid.apache.org by kp...@apache.org on 2022/01/14 18:32:14 UTC
[qpid-proton] 01/01: PROTON-2060: Proposed doc changes to clarify auto-settle usage
This is an automated email from the ASF dual-hosted git repository.
kpvdr pushed a commit to branch PROTON-2060
in repository https://gitbox.apache.org/repos/asf/qpid-proton.git
commit c2906a2cb10ef49d4562f124a74227044d062a8f
Author: Kim van der Riet <kv...@redhat.com>
AuthorDate: Fri Jan 14 13:30:28 2022 -0500
PROTON-2060: Proposed doc changes to clarify auto-settle usage
---
c/include/proton/delivery.h | 6 ++++++
cpp/include/proton/sender_options.hpp | 11 ++++++++++-
python/proton/_handlers.py | 28 ++++++++++++++++++++++++----
ruby/lib/core/sender.rb | 11 ++++++++---
4 files changed, 48 insertions(+), 8 deletions(-)
diff --git a/c/include/proton/delivery.h b/c/include/proton/delivery.h
index 118fbf6..47e8203 100644
--- a/c/include/proton/delivery.h
+++ b/c/include/proton/delivery.h
@@ -287,6 +287,12 @@ PN_EXTERN void pn_delivery_abort(pn_delivery_t *delivery);
* @note If pn_delivery_current(delivery) is true before the call then
* pn_link_advance(pn_delivery_link(deliver)) is called automatically.
*
+ * @note The sender **should not** settle after only receiving a terminal
+ * status disposition with no settle flag, as then there would then be no way
+ * to receive any further events for that delivery (such as the subsequent
+ * on_settle message that might be expected when the receiver finally settles
+ * the message).
+ *
* @param[in] delivery a delivery object
*/
PN_EXTERN void pn_delivery_settle(pn_delivery_t *delivery);
diff --git a/cpp/include/proton/sender_options.hpp b/cpp/include/proton/sender_options.hpp
index 143db3f..acb3f1e 100644
--- a/cpp/include/proton/sender_options.hpp
+++ b/cpp/include/proton/sender_options.hpp
@@ -82,7 +82,16 @@ class sender_options {
/// Set the delivery mode on the sender.
PN_CPP_EXTERN sender_options& delivery_mode(delivery_mode);
- /// Automatically settle messages (default is true).
+ /**
+ * Automatically settle messages (default is true).
+ *
+ * \note
+ * Sender **auto-settlement** only occurs for a delivery after the
+ * sender receives a settled disposition for that delivery. Otherwise,
+ * there would be no way to receive any further events for that delivery
+ * (such as the subsequent on_settle message that might be expected when
+ * the receiver finally settles the message).
+ */
PN_CPP_EXTERN sender_options& auto_settle(bool);
/// Options for the source node of the sender.
diff --git a/python/proton/_handlers.py b/python/proton/_handlers.py
index 1a7849c..cb9ffcb 100644
--- a/python/proton/_handlers.py
+++ b/python/proton/_handlers.py
@@ -50,6 +50,10 @@ class OutgoingMessageHandler(Handler):
:param auto_settle: If ``True``, settle all messages (default). Otherwise
messages must be explicitly settled.
+
+ .. note:: Sender auto-settlement only occurs for a delivery after the
+ sender receives a settled disposition for that delivery.
+
:type auto_settle: ``bool``
:param delegate: A client handler for the endpoint event
"""
@@ -663,11 +667,19 @@ class MessagingHandler(Handler, Acking):
simpler to deal with and/or avoids repetitive tasks for common use
cases.
+ .. note:: Sender **auto-settlement** only occurs for a delivery after the
+ sender receives a settled disposition for that delivery. Otherwise,
+ there would be no way to receive any further events for that delivery
+ (such as the subsequent on_settle message that might be expected when
+ the receiver finally settles the message).
+
:param prefetch: Initial flow credit for receiving messages, defaults to 10.
:param auto_accept: If ``True``, accept all messages (default). Otherwise
messages must be individually accepted or rejected.
:param auto_settle: If ``True``, settle all messages (default). Otherwise
- messages must be explicitly settled.
+ messages must be explicitly settled. Sender auto-settlement only occurs
+ for a delivery after the sender receives a settled disposition for that
+ delivery.
:param peer_close_is_error: If ``True``, a peer endpoint closing will be
treated as an error with an error callback. Otherwise (default), the
normal callbacks for the closing will occur.
@@ -950,11 +962,19 @@ class TransactionalClientHandler(MessagingHandler, TransactionHandler):
and provides a convenience method :meth:`accept` for performing
a transactional acceptance of received messages.
+ .. note:: Sender **auto-settlement** only occurs for a delivery after the
+ sender receives a settled disposition for that delivery. Otherwise,
+ there would be no way to receive any further events for that delivery
+ (such as the subsequent on_settle message that might be expected when
+ the receiver finally settles the message).
+
:param prefetch: Initial flow credit for receiving messages, defaults to 10.
- :param auto_accept: If ``True``, accept all messages (default). Otherwise messages
- must be individually accepted or rejected.
+ :param auto_accept: If ``True``, accept all messages (default). Otherwise
+ messages must be individually accepted or rejected.
:param auto_settle: If ``True``, settle all messages (default). Otherwise
- messages must be explicitly settled.
+ messages must be explicitly settled. Sender auto-settlement only occurs
+ for a delivery after the sender receives a settled disposition for that
+ delivery.
:param peer_close_is_error: If ``True``, a peer endpoint closing will be
treated as an error with an error callback. Otherwise (default), the
normal callbacks for the closing will occur.
diff --git a/ruby/lib/core/sender.rb b/ruby/lib/core/sender.rb
index ff035cb..3e5ef00 100644
--- a/ruby/lib/core/sender.rb
+++ b/ruby/lib/core/sender.rb
@@ -29,10 +29,17 @@ module Qpid::Proton
# Open the {Sender} link
#
+ # @note Sender **auto-settlement** only occurs for a delivery after the
+ # sender receives a settled disposition for that delivery. Otherwise,
+ # there would be no way to receive any further events for that delivery
+ # (such as the subsequent on_settle message that might be expected when
+ # the receiver finally settles the message).
# @overload open_sender(address)
# @param address [String] address of the target to send to
# @overload open_sender(opts)
- # @option opts [Boolean] :auto_settle (true) if true, automatically settle transfers
+ # @option opts [Boolean] :auto_settle (true) if true, automatically settle transfers.
+ # **Note:** Sender auto-settlement only occurs for a delivery after the sender receives
+ # a settled disposition for that delivery.
# @option opts [Boolean] :dynamic (false) dynamic property for source {Terminus#dynamic}
# @option opts [String,Hash] :source source address or source options, see {Terminus#apply}
# @option opts [String,Hash] :target target address or target options, see {Terminus#apply}
@@ -95,5 +102,3 @@ module Qpid::Proton
can_raise_error :stream, :error_class => Qpid::Proton::LinkError
end
end
-
-
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org