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 <[email protected]> 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: [email protected] For additional commands, e-mail: [email protected]
