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
The following commit(s) were added to refs/heads/PROTON-2060 by this push:
new 3acb26b Updated docs according to discussion on PR#354
3acb26b is described below
commit 3acb26bbcc7a7d595cf1222ad0bb64122c7b4301
Author: Kim van der Riet <k...@apache.org>
AuthorDate: Tue Feb 22 17:18:44 2022 -0500
Updated docs according to discussion on PR#354
---
c/include/proton/delivery.h | 6 ------
cpp/include/proton/sender_options.hpp | 10 ++--------
python/proton/_handlers.py | 33 ++++++++-------------------------
ruby/lib/core/sender.rb | 11 +++--------
4 files changed, 13 insertions(+), 47 deletions(-)
diff --git a/c/include/proton/delivery.h b/c/include/proton/delivery.h
index 47e8203..118fbf6 100644
--- a/c/include/proton/delivery.h
+++ b/c/include/proton/delivery.h
@@ -287,12 +287,6 @@ 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 acb3f1e..5b5222d 100644
--- a/cpp/include/proton/sender_options.hpp
+++ b/cpp/include/proton/sender_options.hpp
@@ -83,14 +83,8 @@ class sender_options {
PN_CPP_EXTERN sender_options& delivery_mode(delivery_mode);
/**
- * 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).
+ * If ``True`` (default), automatically settle messages upon receiving a
settled
+ * disposition for that delivery. Otherwise messages must be explicitly
settled.
*/
PN_CPP_EXTERN sender_options& auto_settle(bool);
diff --git a/python/proton/_handlers.py b/python/proton/_handlers.py
index cb9ffcb..ac783d0 100644
--- a/python/proton/_handlers.py
+++ b/python/proton/_handlers.py
@@ -48,12 +48,9 @@ class OutgoingMessageHandler(Handler):
A utility for simpler and more intuitive handling of delivery
events related to outgoing i.e. sent messages.
- :param auto_settle: If ``True``, settle all messages (default). Otherwise
+ :param auto_settle: If ``True`` (default), automatically settle messages
+ upon receiving a settled disposition for that delivery. 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
"""
@@ -667,19 +664,12 @@ 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. Sender auto-settlement only occurs
- for a delivery after the sender receives a settled disposition for that
- delivery.
+ :param auto_settle: If ``True`` (default), automatically settle messages
+ upon receiving a settled disposition for that delivery. Otherwise
+ messages must be explicitly settled.
: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.
@@ -962,19 +952,12 @@ 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_settle: If ``True``, settle all messages (default). Otherwise
- messages must be explicitly settled. Sender auto-settlement only occurs
- for a delivery after the sender receives a settled disposition for that
- delivery.
+ :param auto_settle: If ``True`` (default), automatically settle messages
+ upon receiving a settled disposition for that delivery. Otherwise
+ messages must be explicitly settled.
: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 3e5ef00..3769751 100644
--- a/ruby/lib/core/sender.rb
+++ b/ruby/lib/core/sender.rb
@@ -29,17 +29,12 @@ 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.
- # **Note:** Sender auto-settlement only occurs for a delivery after
the sender receives
- # a settled disposition for that delivery.
+ # @option opts [Boolean] :auto_settle (true) If true (default),
automatically settle
+ # messages upon receiving a settled disposition for that delivery.
Otherwise messages
+ # must be explicitly settled.
# @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}
---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscr...@qpid.apache.org
For additional commands, e-mail: commits-h...@qpid.apache.org
