[qpid-proton] 03/03: PROTON-2673: clarify doc for pn_raw_connection_wake()

[cl...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

cliffjansen pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/qpid-proton.git

commit f13bb8132d9e744c4bc4ff66d283f9d4e34965f8
Author: Clifford Jansen <cl...@apache.org>
AuthorDate: Thu Mar 23 23:53:12 2023 -0700

    PROTON-2673: clarify doc for pn_raw_connection_wake()
---
 c/include/proton/raw_connection.h | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/c/include/proton/raw_connection.h b/c/include/proton/raw_connection.h
index d19ff6dc5..ef5fd33a7 100644
--- a/c/include/proton/raw_connection.h
+++ b/c/include/proton/raw_connection.h
@@ -244,10 +244,19 @@ PNP_EXTERN bool pn_raw_connection_is_write_closed(pn_raw_connection_t *connectio
  * Return a @ref PN_RAW_CONNECTION_WAKE event for @p connection as soon as possible.
  *
  * At least one wake event will be returned, serialized with other @ref proactor_events
- * for the same raw connection.  Wakes can be "coalesced" - if several
+ * for the same raw connection, except as noted.  Wakes can be "coalesced" - if several
  * @ref pn_raw_connection_wake() calls happen close together, there may be only one
  * @ref PN_RAW_CONNECTION_WAKE event that occurs after all of them.
  *
+ * A @ref PN_RAW_CONNECTION_WAKE event will never follow a
+ * @ref PN_RAW_CONNECTION_DISCONNECTED event. I.e. it will be dropped.
+ *
+ * The result of this call is undefined if called after a @ref PN_RAW_CONNECTION_DISCONNECTED
+ * event has been delivered and its event batch has been released by a call to
+ * @ref pn_proactor_done().  It is also undefined if called before the return of either
+ * @ref pn_proactor_raw_connect() or @ref pn_listener_raw_accept() for client or server
+ * raw connections respectively.
+ *
  * @note Thread-safe
  */
 PNP_EXTERN void pn_raw_connection_wake(pn_raw_connection_t *connection);


---------------------------------------------------------------------
To unsubscribe, e-mail: commits-unsubscribe@qpid.apache.org
For additional commands, e-mail: commits-help@qpid.apache.org