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:13 UTC
[qpid-proton] branch PROTON-2060 created (now c2906a2)
This is an automated email from the ASF dual-hosted git repository.
kpvdr pushed a change to branch PROTON-2060
in repository https://gitbox.apache.org/repos/asf/qpid-proton.git.
at c2906a2 PROTON-2060: Proposed doc changes to clarify auto-settle usage
This branch includes the following new commits:
new c2906a2 PROTON-2060: Proposed doc changes to clarify auto-settle usage
The 1 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails. The revisions
listed as "add" were already present in the repository and have only
been added to this reference.
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org
[qpid-proton] 01/01: PROTON-2060: Proposed doc changes to clarify auto-settle usage
Posted by kp...@apache.org.
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