[59/89] [abbrv] qpid-proton git commit: PROTON-636, PROTON-1809, PROTON-1523: update session capacity api doc to clarify its behaviour

[ac...@apache.org]

PROTON-636, PROTON-1809, PROTON-1523: update session capacity api doc to clarify its behaviour


Project: http://git-wip-us.apache.org/repos/asf/qpid-proton/repo
Commit: http://git-wip-us.apache.org/repos/asf/qpid-proton/commit/d58bd715
Tree: http://git-wip-us.apache.org/repos/asf/qpid-proton/tree/d58bd715
Diff: http://git-wip-us.apache.org/repos/asf/qpid-proton/diff/d58bd715

Branch: refs/heads/go1
Commit: d58bd7154558a3be3a68dfee71f08c7d76bad958
Parents: 0772e2e
Author: Robbie Gemmell <ro...@apache.org>
Authored: Wed Apr 11 11:33:05 2018 +0100
Committer: Robbie Gemmell <ro...@apache.org>
Committed: Wed Apr 11 11:33:05 2018 +0100

----------------------------------------------------------------------
 c/include/proton/session.h | 15 ++++++++++-----
 1 file changed, 10 insertions(+), 5 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/qpid-proton/blob/d58bd715/c/include/proton/session.h
----------------------------------------------------------------------
diff --git a/c/include/proton/session.h b/c/include/proton/session.h
index 512e004..21023a8 100644
--- a/c/include/proton/session.h
+++ b/c/include/proton/session.h
@@ -198,7 +198,7 @@ PN_EXTERN void pn_session_close(pn_session_t *session);
  * Get the incoming capacity of the session measured in bytes.
  *
  * The incoming capacity of a session determines how much incoming
- * message data the session will buffer.
+ * message data the session can buffer.
  *
  * @param[in] session the session object
  * @return the incoming capacity of the session in bytes
@@ -208,14 +208,19 @@ PN_EXTERN size_t pn_session_get_incoming_capacity(pn_session_t *session);
 /**
  * Set the incoming capacity for a session object.
  *
- * The incoming capacity of a session determines how much incoming
- * message data the session will buffer.
+ * The incoming capacity of a session determines how much incoming message
+ * data the session can buffer, by governing the size of the session
+ * incoming-window for transfer frames. This happens in concert with the
+ * transport max frame size, and only when both values have been set.
  *
  * NOTE: If set, this value must be greater than or equal to the negotiated
- * frame size of the transport.
+ * frame size of the transport. The window is computed as a whole number of
+ * frames when dividing remaining capacity at a given time by the connection
+ * max frame size. As such, capacity and max frame size should be chosen so
+ * as to ensure the frame window isn't unduly small and limiting performance.
  *
  * @param[in] session the session object
- * @param[in] capacity the incoming capacity for the session
+ * @param[in] capacity the incoming capacity for the session in bytes
  */
 PN_EXTERN void pn_session_set_incoming_capacity(pn_session_t *session, size_t capacity);
 


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