input/releases/qpid-proton-0.32.0/proton/c/api/buffering.html - qpid-site - Git at Google

 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
 <meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
 <meta http-equiv="X-UA-Compatible" content="IE=9"/>
 <meta name="generator" content="Doxygen 1.8.20"/>
 <meta name="viewport" content="width=device-width, initial-scale=1"/>
 <title>Qpid Proton C API: Buffering</title>
 <link href="tabs.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="jquery.js"></script>
 <script type="text/javascript" src="dynsections.js"></script>
 <link href="navtree.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="resize.js"></script>
 <script type="text/javascript" src="navtreedata.js"></script>
 <script type="text/javascript" src="navtree.js"></script>
 <link href="search/search.css" rel="stylesheet" type="text/css"/>
 <script type="text/javascript" src="search/searchdata.js"></script>
 <script type="text/javascript" src="search/search.js"></script>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
   $(document).ready(function() { init_search(); });
 /* @license-end */
 </script>
 <link href="doxygen.css" rel="stylesheet" type="text/css" />
 </head>
 <body>
 <div id="top"><!-- do not remove this div, it is closed by doxygen! -->
 <div id="titlearea">
 <table cellspacing="0" cellpadding="0">
  <tbody>
  <tr style="height: 56px;">
   <td id="projectalign" style="padding-left: 0.5em;">
    <div id="projectname">Qpid Proton C API
    &#160;<span id="projectnumber">0.32.0</span>
    </div>
   </td>
    <td>        <div id="MSearchBox" class="MSearchBoxInactive">
         <span class="left">
           <img id="MSearchSelect" src="search/mag_sel.svg"
                onmouseover="return searchBox.OnSearchSelectShow()"
                onmouseout="return searchBox.OnSearchSelectHide()"
                alt=""/>
           <input type="text" id="MSearchField" value="Search" accesskey="S"
                onfocus="searchBox.OnSearchFieldFocus(true)"
                onblur="searchBox.OnSearchFieldFocus(false)"
                onkeyup="searchBox.OnSearchFieldChange(event)"/>
           </span><span class="right">
             <a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
           </span>
         </div>
 </td>
  </tr>
  </tbody>
 </table>
 </div>
 <!-- end header part -->
 <!-- Generated by Doxygen 1.8.20 -->
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 var searchBox = new SearchBox("searchBox", "search",false,'Search');
 /* @license-end */
 </script>
 </div><!-- top -->
 <div id="side-nav" class="ui-resizable side-nav-resizable">
   <div id="nav-tree">
     <div id="nav-tree-contents">
       <div id="nav-sync" class="sync"></div>
     </div>
   </div>
   <div id="splitbar" style="-moz-user-select:none;"
        class="ui-resizable-handle">
   </div>
 </div>
 <script type="text/javascript">
 /* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&amp;dn=gpl-2.0.txt GPL-v2 */
 $(document).ready(function(){initNavTree('buffering.html',''); initResizable(); });
 /* @license-end */
 </script>
 <div id="doc-content">
 <!-- window showing the filter options -->
 <div id="MSearchSelectWindow"
      onmouseover="return searchBox.OnSearchSelectShow()"
      onmouseout="return searchBox.OnSearchSelectHide()"
      onkeydown="return searchBox.OnSearchSelectKey(event)">
 </div>

 <!-- iframe showing the search results (closed by default) -->
 <div id="MSearchResultsWindow">
 <iframe src="javascript:void(0)" frameborder="0"
         name="MSearchResults" id="MSearchResults">
 </iframe>
 </div>

 <div class="PageDoc"><div class="header">
   <div class="headertitle">
 <div class="title">Buffering </div>  </div>
 </div><!--header-->
 <div class="contents">
 <div class="textblock"><p><a class="anchor" id="md__tmp_rgemmell_transom_qpid-proton-0"></a>.32.0_c_docs_buffering</p>
 <p>AMQP and proton have mechanisms to allow an application to control it's use of memory.</p>
 <h2><a class="anchor" id="autotoc_md10"></a>
 Outgoing Data</h2>
 <p>The unit of memory control in AMQP is the <em>session</em>. <code><a class="el" href="group__session.html#gabcae388cdcb33e976b490525ec600b50" title="Get the number of outgoing bytes currently buffered by a session.">pn_session_outgoing_bytes()</a></code> tells you the total bytes buffered for all outgoing deliveries on all sending links belonging to that session.</p>
 <p>Each call to <code><a class="el" href="group__link.html#gaa825fac21730f3f9fff37d156e5f88e9" title="Send message data for the current delivery on a link.">pn_link_send()</a></code> adds to the session's outgoing byte total. Each time proton writes data to the network it reduces the total. To control the memory used by a session, check <code><a class="el" href="group__session.html#gabcae388cdcb33e976b490525ec600b50" title="Get the number of outgoing bytes currently buffered by a session.">pn_session_outgoing_bytes()</a></code> before calling <code><a class="el" href="group__link.html#gaa825fac21730f3f9fff37d156e5f88e9" title="Send message data for the current delivery on a link.">pn_link_send()</a></code>. If it is too high, stop sending until the link gets a <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa4eaecc54c07cdc9b0df7b1d536a7dc3f">PN_LINK_FLOW</a> event.</p>
 <p>The AMQP protocol allows peers to exchange session limits so they can predict their buffering requirements for incoming data ( <code><a class="el" href="group__session.html#gaedc306d86e778cbf8eaaf528c3eacae9" title="Set the incoming capacity for a session object.">pn_session_set_incoming_capacity()</a></code> and <code><a class="el" href="group__session.html#gaca5962e539688b4f31b5b91136aa3c79" title="Set the outgoing window for a session object.">pn_session_set_outgoing_window()</a></code>). Proton will not exceed those limits when sending to or receiving from the peer. However proton does <em>not</em> limit the amount of data buffered in local memory at the request of the application. It is up to the application to ensure it does not request more memory than it wants proton to use.</p>
 <h3><a class="anchor" id="autotoc_md11"></a>
 Priority</h3>
 <p>Data written on different links can be interleaved with data from any other link on the same connection when sending to the peer. Proton does not make any formal guarantee of fairness, and does not enforce any kind of priority when deciding how to order frames for sending. Using separate links and/or sessions for high-priority messages means their frames <em>can</em> be sent before already-buffered low-priority frames, but there is no guarantee that they <em>will</em>.</p>
 <p>If you need to ensure swift delivery of higher-priority messages on the same connection as lower-priority ones, then you should control the amount of data buffered by proton, and buffer the backlog of low-priority backlog in your own application.</p>
 <p>There is no point in letting proton buffer more than the outgoing session limits since that's all it can transmit without peer confirmation. You may want to buffer less, depending on how you value the trade-off between reducing max latency for high-priority messages (smaller buffer) and increasing max throughput under load (bigger buffer).</p>
 <h2><a class="anchor" id="autotoc_md12"></a>
 Incoming Data</h2>
 <p>To Be Done... </p>
 </div></div><!-- contents -->
 </div><!-- PageDoc -->
 </div><!-- doc-content -->
 <!-- start footer part -->
 <div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
   <ul>
     <li class="footer">Generated by <a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20 </li>
   </ul>
 </div>
 </body>
 </html>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
	<meta http-equiv="X-UA-Compatible" content="IE=9"/>
	<meta name="generator" content="Doxygen 1.8.20"/>
	<meta name="viewport" content="width=device-width, initial-scale=1"/>
	<title>Qpid Proton C API: Buffering</title>
	<link href="tabs.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="jquery.js"></script>
	<script type="text/javascript" src="dynsections.js"></script>
	<link href="navtree.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="resize.js"></script>
	<script type="text/javascript" src="navtreedata.js"></script>
	<script type="text/javascript" src="navtree.js"></script>
	<link href="search/search.css" rel="stylesheet" type="text/css"/>
	<script type="text/javascript" src="search/searchdata.js"></script>
	<script type="text/javascript" src="search/search.js"></script>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(document).ready(function() { init_search(); });
	/* @license-end */
	</script>
	<link href="doxygen.css" rel="stylesheet" type="text/css" />
	</head>
	<body>
	<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
	<div id="titlearea">
	<table cellspacing="0" cellpadding="0">
	<tbody>
	<tr style="height: 56px;">
	<td id="projectalign" style="padding-left: 0.5em;">
	<div id="projectname">Qpid Proton C API
	<span id="projectnumber">0.32.0</span>
	</div>
	</td>
	<td> <div id="MSearchBox" class="MSearchBoxInactive">
	<span class="left">
	<img id="MSearchSelect" src="search/mag_sel.svg"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	alt=""/>
	<input type="text" id="MSearchField" value="Search" accesskey="S"
	onfocus="searchBox.OnSearchFieldFocus(true)"
	onblur="searchBox.OnSearchFieldFocus(false)"
	onkeyup="searchBox.OnSearchFieldChange(event)"/>
	</span><span class="right">
	<a id="MSearchClose" href="javascript:searchBox.CloseResultsWindow()"><img id="MSearchCloseImg" border="0" src="search/close.svg" alt=""/></a>
	</span>
	</div>
	</td>
	</tr>
	</tbody>
	</table>
	</div>
	<!-- end header part -->
	<!-- Generated by Doxygen 1.8.20 -->
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	var searchBox = new SearchBox("searchBox", "search",false,'Search');
	/* @license-end */
	</script>
	</div><!-- top -->
	<div id="side-nav" class="ui-resizable side-nav-resizable">
	<div id="nav-tree">
	<div id="nav-tree-contents">
	<div id="nav-sync" class="sync"></div>
	</div>
	</div>
	<div id="splitbar" style="-moz-user-select:none;"
	class="ui-resizable-handle">
	</div>
	</div>
	<script type="text/javascript">
	/* @license magnet:?xt=urn:btih:cf05388f2679ee054f2beb29a391d25f4e673ac3&dn=gpl-2.0.txt GPL-v2 */
	$(document).ready(function(){initNavTree('buffering.html',''); initResizable(); });
	/* @license-end */
	</script>
	<div id="doc-content">
	<!-- window showing the filter options -->
	<div id="MSearchSelectWindow"
	onmouseover="return searchBox.OnSearchSelectShow()"
	onmouseout="return searchBox.OnSearchSelectHide()"
	onkeydown="return searchBox.OnSearchSelectKey(event)">
	</div>

	<!-- iframe showing the search results (closed by default) -->
	<div id="MSearchResultsWindow">
	<iframe src="javascript:void(0)" frameborder="0"
	name="MSearchResults" id="MSearchResults">
	</iframe>
	</div>

	<div class="PageDoc"><div class="header">
	<div class="headertitle">
	<div class="title">Buffering </div> </div>
	</div><!--header-->
	<div class="contents">
	<div class="textblock"><p><a class="anchor" id="md__tmp_rgemmell_transom_qpid-proton-0"></a>.32.0_c_docs_buffering</p>
	<p>AMQP and proton have mechanisms to allow an application to control it's use of memory.</p>
	<h2><a class="anchor" id="autotoc_md10"></a>
	Outgoing Data</h2>
	<p>The unit of memory control in AMQP is the <em>session</em>. <code><a class="el" href="group__session.html#gabcae388cdcb33e976b490525ec600b50" title="Get the number of outgoing bytes currently buffered by a session.">pn_session_outgoing_bytes()</a></code> tells you the total bytes buffered for all outgoing deliveries on all sending links belonging to that session.</p>
	<p>Each call to <code><a class="el" href="group__link.html#gaa825fac21730f3f9fff37d156e5f88e9" title="Send message data for the current delivery on a link.">pn_link_send()</a></code> adds to the session's outgoing byte total. Each time proton writes data to the network it reduces the total. To control the memory used by a session, check <code><a class="el" href="group__session.html#gabcae388cdcb33e976b490525ec600b50" title="Get the number of outgoing bytes currently buffered by a session.">pn_session_outgoing_bytes()</a></code> before calling <code><a class="el" href="group__link.html#gaa825fac21730f3f9fff37d156e5f88e9" title="Send message data for the current delivery on a link.">pn_link_send()</a></code>. If it is too high, stop sending until the link gets a <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa4eaecc54c07cdc9b0df7b1d536a7dc3f">PN_LINK_FLOW</a> event.</p>
	<p>The AMQP protocol allows peers to exchange session limits so they can predict their buffering requirements for incoming data ( <code><a class="el" href="group__session.html#gaedc306d86e778cbf8eaaf528c3eacae9" title="Set the incoming capacity for a session object.">pn_session_set_incoming_capacity()</a></code> and <code><a class="el" href="group__session.html#gaca5962e539688b4f31b5b91136aa3c79" title="Set the outgoing window for a session object.">pn_session_set_outgoing_window()</a></code>). Proton will not exceed those limits when sending to or receiving from the peer. However proton does <em>not</em> limit the amount of data buffered in local memory at the request of the application. It is up to the application to ensure it does not request more memory than it wants proton to use.</p>
	<h3><a class="anchor" id="autotoc_md11"></a>
	Priority</h3>
	<p>Data written on different links can be interleaved with data from any other link on the same connection when sending to the peer. Proton does not make any formal guarantee of fairness, and does not enforce any kind of priority when deciding how to order frames for sending. Using separate links and/or sessions for high-priority messages means their frames <em>can</em> be sent before already-buffered low-priority frames, but there is no guarantee that they <em>will</em>.</p>
	<p>If you need to ensure swift delivery of higher-priority messages on the same connection as lower-priority ones, then you should control the amount of data buffered by proton, and buffer the backlog of low-priority backlog in your own application.</p>
	<p>There is no point in letting proton buffer more than the outgoing session limits since that's all it can transmit without peer confirmation. You may want to buffer less, depending on how you value the trade-off between reducing max latency for high-priority messages (smaller buffer) and increasing max throughput under load (bigger buffer).</p>
	<h2><a class="anchor" id="autotoc_md12"></a>
	Incoming Data</h2>
	<p>To Be Done... </p>
	</div></div><!-- contents -->
	</div><!-- PageDoc -->
	</div><!-- doc-content -->
	<!-- start footer part -->
	<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
	<ul>
	<li class="footer">Generated by <a href="http://www.doxygen.org/index.html"><img class="footer" src="doxygen.svg" width="104" height="31" alt="doxygen"/></a> 1.8.20 </li>
	</ul>
	</div>
	</body>
	</html>