input/releases/qpid-proton-0.32.0/proton/c/api/threads.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: Multithreading</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('threads.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">Multithreading </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_threads</p>
 <p>The <a class="el" href="group__proactor.html#gac2a925b3de00efd8cd40fa9920169554">pn_proactor</a> allows you to create multi-threaded client and server applications. You can call <code>pn_proactor_run</code> in multiple threads to create a thread pool for proton to handle events and IO.</p>
 <p>The <a class="el" href="group__proactor.html">Proactor</a> functions are safe to call from any thread. Most other functions are <b>not</b> safe to call concurrently. The following rules applies: objects and events associated with <em>different</em> connections can safely be used concurrently. Objects and events associated with <em>the same</em> connection cannot.</p>
 <p>The proactor helps you to handle connections safely: <code><a class="el" href="group__proactor.html#ga957eae24db6ec4962af79c5a06106115" title="Return Proactor events if any are available immediately.">pn_proactor_get()</a></code> and <code><a class="el" href="group__proactor.html#ga2b66a46f3e557010ec61bd105326753d" title="Wait until there are Proactor events to handle.">pn_proactor_wait()</a></code> will never return events associated with the same connection to different threads concurrently. As long as you process only the objects available from the event returned by the proactor, you are in no danger.</p>
 <p>When you need to process objects belonging to a <em>different</em> connection (for example if you receive a message on one connection and want to send it on another) you must use locks and thread safe data structures and the <code><a class="el" href="group__proactor.html#ga0f49c771fe3bff54f58c9d583ca30560" title="Return a PN_CONNECTION_WAKE event for connection as soon as possible.">pn_connection_wake()</a></code> function.</p>
 <h2><a class="anchor" id="autotoc_md17"></a>
 The wake function</h2>
 <p><code><a class="el" href="group__proactor.html#ga0f49c771fe3bff54f58c9d583ca30560" title="Return a PN_CONNECTION_WAKE event for connection as soon as possible.">pn_connection_wake()</a></code> can be called from any thread as long as the <code>pn_connection_t</code> has not been freed. It allows any thread to "wake up" a connection by generating a <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa28a2bfee806bbc1fe31499c8eec39db0">PN_CONNECTION_WAKE</a> event for that connection.</p>
 <p>For example, supposed a message arrives on connection A and must be sent on connection B. The thread that receives events for A from the proactor can safely call <code><a class="el" href="group__link.html#ga06c97ce7396973dca0d311567f25f95a" title="Receive message data for the current delivery on a link.">pn_link_recv()</a></code> on A's link to decode the <a class="el" href="group__message.html">Message</a>. However it cannot call <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> on any link belonging to B.</p>
 <p>The decoded <a class="el" href="group__message.html">Message</a> is independent of any connection, so the thread handling A can store the message in a thread-safe data structure, and call <code><a class="el" href="group__proactor.html#ga0f49c771fe3bff54f58c9d583ca30560" title="Return a PN_CONNECTION_WAKE event for connection as soon as possible.">pn_connection_wake()</a></code> to notify B. Shortly after, some thread will get a <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa28a2bfee806bbc1fe31499c8eec39db0">PN_CONNECTION_WAKE</a> event for B, and can retrieve the message and send it on B's link.</p>
 <dl class="section note"><dt>Note</dt><dd>Be careful to ensure (using a mutex for example) that connection B cannot be deleted before connection A calls <code>pn_connection_wake</code>. Connections are automatically deleted by the proactor after the <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa1ca722ce3c0b2c13a33636cded8430ba">PN_TRANSPORT_CLOSED</a> event git </dd></dl>
 </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: Multithreading</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('threads.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">Multithreading </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_threads</p>
	<p>The <a class="el" href="group__proactor.html#gac2a925b3de00efd8cd40fa9920169554">pn_proactor</a> allows you to create multi-threaded client and server applications. You can call <code>pn_proactor_run</code> in multiple threads to create a thread pool for proton to handle events and IO.</p>
	<p>The <a class="el" href="group__proactor.html">Proactor</a> functions are safe to call from any thread. Most other functions are <b>not</b> safe to call concurrently. The following rules applies: objects and events associated with <em>different</em> connections can safely be used concurrently. Objects and events associated with <em>the same</em> connection cannot.</p>
	<p>The proactor helps you to handle connections safely: <code><a class="el" href="group__proactor.html#ga957eae24db6ec4962af79c5a06106115" title="Return Proactor events if any are available immediately.">pn_proactor_get()</a></code> and <code><a class="el" href="group__proactor.html#ga2b66a46f3e557010ec61bd105326753d" title="Wait until there are Proactor events to handle.">pn_proactor_wait()</a></code> will never return events associated with the same connection to different threads concurrently. As long as you process only the objects available from the event returned by the proactor, you are in no danger.</p>
	<p>When you need to process objects belonging to a <em>different</em> connection (for example if you receive a message on one connection and want to send it on another) you must use locks and thread safe data structures and the <code><a class="el" href="group__proactor.html#ga0f49c771fe3bff54f58c9d583ca30560" title="Return a PN_CONNECTION_WAKE event for connection as soon as possible.">pn_connection_wake()</a></code> function.</p>
	<h2><a class="anchor" id="autotoc_md17"></a>
	The wake function</h2>
	<p><code><a class="el" href="group__proactor.html#ga0f49c771fe3bff54f58c9d583ca30560" title="Return a PN_CONNECTION_WAKE event for connection as soon as possible.">pn_connection_wake()</a></code> can be called from any thread as long as the <code>pn_connection_t</code> has not been freed. It allows any thread to "wake up" a connection by generating a <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa28a2bfee806bbc1fe31499c8eec39db0">PN_CONNECTION_WAKE</a> event for that connection.</p>
	<p>For example, supposed a message arrives on connection A and must be sent on connection B. The thread that receives events for A from the proactor can safely call <code><a class="el" href="group__link.html#ga06c97ce7396973dca0d311567f25f95a" title="Receive message data for the current delivery on a link.">pn_link_recv()</a></code> on A's link to decode the <a class="el" href="group__message.html">Message</a>. However it cannot call <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> on any link belonging to B.</p>
	<p>The decoded <a class="el" href="group__message.html">Message</a> is independent of any connection, so the thread handling A can store the message in a thread-safe data structure, and call <code><a class="el" href="group__proactor.html#ga0f49c771fe3bff54f58c9d583ca30560" title="Return a PN_CONNECTION_WAKE event for connection as soon as possible.">pn_connection_wake()</a></code> to notify B. Shortly after, some thread will get a <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa28a2bfee806bbc1fe31499c8eec39db0">PN_CONNECTION_WAKE</a> event for B, and can retrieve the message and send it on B's link.</p>
	<dl class="section note"><dt>Note</dt><dd>Be careful to ensure (using a mutex for example) that connection B cannot be deleted before connection A calls <code>pn_connection_wake</code>. Connections are automatically deleted by the proactor after the <a class="el" href="group__event.html#gga4876e2eed24a4d4e4c52b99842103cdaa1ca722ce3c0b2c13a33636cded8430ba">PN_TRANSPORT_CLOSED</a> event git </dd></dl>
	</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>