<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://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"/>
<title>Apache Portable Runtime: Resource List Routines</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<link href="search/search.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="search/search.js"></script>
<link href="doxygen.css" rel="stylesheet" type="text/css"/>
</head>
<body onload='searchBox.OnSelectItem(0);'>
<!-- Generated by Doxygen 1.7.3 -->
<script type="text/javascript"><!--
var searchBox = new SearchBox("searchBox", "search",false,'Search');
--></script>
<div id="top">
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
<tbody>
<tr style="height: 56px;">
<td style="padding-left: 0.5em;">
<div id="projectname">Apache Portable Runtime</div>
</td>
</tr>
</tbody>
</table>
</div>
<div id="navrow1" class="tabs">
<ul class="tablist">
<li><a href="index.html"><span>Main Page</span></a></li>
<li><a href="pages.html"><span>Related Pages</span></a></li>
<li><a href="modules.html"><span>Modules</span></a></li>
<li><a href="namespaces.html"><span>Namespaces</span></a></li>
<li><a href="annotated.html"><span>Data Structures</span></a></li>
<li><a href="files.html"><span>Files</span></a></li>
<li id="searchli">
<div id="MSearchBox" class="MSearchBoxInactive">
<span class="left">
<img id="MSearchSelect" src="search/mag_sel.png"
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.png" alt=""/></a>
</span>
</div>
</li>
</ul>
</div>
</div>
<div class="header">
<div class="summary">
<a href="#typedef-members">Typedefs</a> |
<a href="#func-members">Functions</a> </div>
<div class="headertitle">
<h1>Resource List Routines</h1> </div>
<div class="ingroups"><a class="el" href="group___a_p_r___util.html">APR Utility Functions</a></div></div>
<div class="contents">
<table class="memberdecls">
<tr><td colspan="2"><h2><a name="typedef-members"></a>
Typedefs</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top">typedef struct <a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="gab43e73c2fb526476d3e56d51f5aa214c"></a><!-- doxytag: member="APR_Util_RL::apr_reslist_constructor" ref="gab43e73c2fb526476d3e56d51f5aa214c" args=")(void **resource, void *params, apr_pool_t *pool)" -->
typedef <a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a>(* </td><td class="memItemRight" valign="bottom"><b>apr_reslist_constructor</b> )(void **resource, void *params, <a class="el" href="group__apr__pools.html#gaf137f28edcf9a086cd6bc36c20d7cdfb">apr_pool_t</a> *pool)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="anchor" id="ga60813240d319787f0430ae3171af838a"></a><!-- doxytag: member="APR_Util_RL::apr_reslist_destructor" ref="ga60813240d319787f0430ae3171af838a" args=")(void *resource, void *params, apr_pool_t *pool)" -->
typedef <a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a>(* </td><td class="memItemRight" valign="bottom"><b>apr_reslist_destructor</b> )(void *resource, void *params, <a class="el" href="group__apr__pools.html#gaf137f28edcf9a086cd6bc36c20d7cdfb">apr_pool_t</a> *pool)</td></tr>
<tr><td colspan="2"><h2><a name="func-members"></a>
Functions</h2></td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#ga608ebcddce542603a7f1d3cf51ae8d3c">apr_reslist_create</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> **reslist, int min, int smax, int hmax, <a class="el" href="group__apr__time.html#gaae2129185a395cc393f76fabf4f43e47">apr_interval_time_t</a> ttl, apr_reslist_constructor con, apr_reslist_destructor de, void *params, <a class="el" href="group__apr__pools.html#gaf137f28edcf9a086cd6bc36c20d7cdfb">apr_pool_t</a> *pool)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#ga103e0cbac6c5da7cb93d4e52799233cb">apr_reslist_destroy</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> *reslist)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#gadfbb592b31ff9215f45d3280636e41d7">apr_reslist_acquire</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> *reslist, void **resource)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#gaf65ca1701994a0323df639cdb4a8d8b2">apr_reslist_release</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> *reslist, void *resource)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">void </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#gafe06c964d04a568f2625fb5a9ba7bad6">apr_reslist_timeout_set</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> *reslist, <a class="el" href="group__apr__time.html#gaae2129185a395cc393f76fabf4f43e47">apr_interval_time_t</a> timeout)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top">apr_uint32_t </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#gac37fbbcbc8a98ba9ed017638a2c6c1b7">apr_reslist_acquired_count</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> *reslist)</td></tr>
<tr><td class="memItemLeft" align="right" valign="top"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> </td><td class="memItemRight" valign="bottom"><a class="el" href="group___a_p_r___util___r_l.html#ga346c0604115a9659cf23ed0cc781f7a9">apr_reslist_invalidate</a> (<a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> *reslist, void *resource)</td></tr>
</table>
<hr/><a name="_details"></a><h2>Detailed Description</h2>
<dl class="warning"><dt><b>Warning:</b></dt><dd><b><em>Resource list data types and routines are only available when threads are enabled (i.e. APR_HAS_THREADS is not zero).</em></b> </dd></dl>
<hr/><h2>Typedef Documentation</h2>
<a class="anchor" id="ga670f6719dfeffe1037e063eaab7b82ac"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_t" ref="ga670f6719dfeffe1037e063eaab7b82ac" args="" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">typedef struct <a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> <a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Opaque resource list object </p>
</div>
</div>
<hr/><h2>Function Documentation</h2>
<a class="anchor" id="gadfbb592b31ff9215f45d3280636e41d7"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_acquire" ref="gadfbb592b31ff9215f45d3280636e41d7" args="(apr_reslist_t *reslist, void **resource)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> apr_reslist_acquire </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> * </td>
<td class="paramname"><em>reslist</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void ** </td>
<td class="paramname"><em>resource</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Retrieve a resource from the list, creating a new one if necessary. If we have met our maximum number of resources, we will block until one becomes available. </p>
</div>
</div>
<a class="anchor" id="gac37fbbcbc8a98ba9ed017638a2c6c1b7"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_acquired_count" ref="gac37fbbcbc8a98ba9ed017638a2c6c1b7" args="(apr_reslist_t *reslist)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">apr_uint32_t apr_reslist_acquired_count </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> * </td>
<td class="paramname"><em>reslist</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return the number of outstanding resources. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">reslist</td><td>The resource list. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga608ebcddce542603a7f1d3cf51ae8d3c"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_create" ref="ga608ebcddce542603a7f1d3cf51ae8d3c" args="(apr_reslist_t **reslist, int min, int smax, int hmax, apr_interval_time_t ttl, apr_reslist_constructor con, apr_reslist_destructor de, void *params, apr_pool_t *pool)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> apr_reslist_create </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> ** </td>
<td class="paramname"><em>reslist</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>min</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>smax</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">int </td>
<td class="paramname"><em>hmax</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__apr__time.html#gaae2129185a395cc393f76fabf4f43e47">apr_interval_time_t</a> </td>
<td class="paramname"><em>ttl</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">apr_reslist_constructor </td>
<td class="paramname"><em>con</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">apr_reslist_destructor </td>
<td class="paramname"><em>de</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>params</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__apr__pools.html#gaf137f28edcf9a086cd6bc36c20d7cdfb">apr_pool_t</a> * </td>
<td class="paramname"><em>pool</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Create a new resource list with the following parameters: </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">reslist</td><td>An address where the pointer to the new resource list will be stored. </td></tr>
<tr><td class="paramname">min</td><td>Allowed minimum number of available resources. Zero creates new resources only when needed. </td></tr>
<tr><td class="paramname">smax</td><td>Resources will be destroyed during reslist maintenance to meet this maximum restriction as they expire (reach their ttl). </td></tr>
<tr><td class="paramname">hmax</td><td>Absolute maximum limit on the number of total resources. </td></tr>
<tr><td class="paramname">ttl</td><td>If non-zero, sets the maximum amount of time in microseconds an unused resource is valid. Any resource which has exceeded this time will be destroyed, either when encountered by <a class="el" href="group___a_p_r___util___r_l.html#gadfbb592b31ff9215f45d3280636e41d7">apr_reslist_acquire()</a> or during reslist maintenance. </td></tr>
<tr><td class="paramname">con</td><td>Constructor routine that is called to create a new resource. </td></tr>
<tr><td class="paramname">de</td><td>Destructor routine that is called to destroy an expired resource. </td></tr>
<tr><td class="paramname">params</td><td>Passed to constructor and deconstructor </td></tr>
<tr><td class="paramname">pool</td><td>The pool from which to create this resource list. Also the same pool that is passed to the constructor and destructor routines. </td></tr>
</table>
</dd>
</dl>
<dl class="warning"><dt><b>Warning:</b></dt><dd>If you're creating a sub-pool of the pool passed into this function in your constructor, you will need to follow some rules when it comes to destruction of that sub-pool, as calling <a class="el" href="group__apr__pools.html#ga54759954d2cba7cb649ab5680a33f9e3">apr_pool_destroy()</a> outright on it in your destructor may create double free situations. That is because by the time destructor is called, the sub-pool may have already been destroyed. This also means that in the destructor, memory from the sub-pool should be treated as invalid. For examples of how to do this correctly, see mod_dbd of <a class="el" href="namespace_apache.html">Apache</a> 2.2 and memcache support in APR Util 1.3. </dd></dl>
</div>
</div>
<a class="anchor" id="ga103e0cbac6c5da7cb93d4e52799233cb"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_destroy" ref="ga103e0cbac6c5da7cb93d4e52799233cb" args="(apr_reslist_t *reslist)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> apr_reslist_destroy </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> * </td>
<td class="paramname"><em>reslist</em></td><td>)</td>
<td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Destroy the given resource list and all resources controlled by this list. FIXME: Should this block until all resources become available, or maybe just destroy all the free ones, or maybe destroy them even though they might be in use by something else? Currently it will abort if there are resources that haven't been released, so there is an assumption that all resources have been released to the list before calling this function. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">reslist</td><td>The reslist to destroy </td></tr>
</table>
</dd>
</dl>
</div>
</div>
<a class="anchor" id="ga346c0604115a9659cf23ed0cc781f7a9"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_invalidate" ref="ga346c0604115a9659cf23ed0cc781f7a9" args="(apr_reslist_t *reslist, void *resource)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> apr_reslist_invalidate </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> * </td>
<td class="paramname"><em>reslist</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>resource</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Invalidate a resource in the pool - e.g. a database connection that returns a "lost connection" error and can't be restored. Use this instead of apr_reslist_release if the resource is bad. </p>
</div>
</div>
<a class="anchor" id="gaf65ca1701994a0323df639cdb4a8d8b2"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_release" ref="gaf65ca1701994a0323df639cdb4a8d8b2" args="(apr_reslist_t *reslist, void *resource)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname"><a class="el" href="group__apr__errno.html#gaf76ee4543247e9fb3f3546203e590a6c">apr_status_t</a> apr_reslist_release </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> * </td>
<td class="paramname"><em>reslist</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype">void * </td>
<td class="paramname"><em>resource</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Return a resource back to the list of available resources. </p>
</div>
</div>
<a class="anchor" id="gafe06c964d04a568f2625fb5a9ba7bad6"></a><!-- doxytag: member="apr_reslist.h::apr_reslist_timeout_set" ref="gafe06c964d04a568f2625fb5a9ba7bad6" args="(apr_reslist_t *reslist, apr_interval_time_t timeout)" -->
<div class="memitem">
<div class="memproto">
<table class="memname">
<tr>
<td class="memname">void apr_reslist_timeout_set </td>
<td>(</td>
<td class="paramtype"><a class="el" href="group___a_p_r___util___r_l.html#ga670f6719dfeffe1037e063eaab7b82ac">apr_reslist_t</a> * </td>
<td class="paramname"><em>reslist</em>, </td>
</tr>
<tr>
<td class="paramkey"></td>
<td></td>
<td class="paramtype"><a class="el" href="group__apr__time.html#gaae2129185a395cc393f76fabf4f43e47">apr_interval_time_t</a> </td>
<td class="paramname"><em>timeout</em> </td>
</tr>
<tr>
<td></td>
<td>)</td>
<td></td><td></td>
</tr>
</table>
</div>
<div class="memdoc">
<p>Set the timeout the acquire will wait for a free resource when the maximum number of resources is exceeded. </p>
<dl><dt><b>Parameters:</b></dt><dd>
<table class="params">
<tr><td class="paramname">reslist</td><td>The resource list. </td></tr>
<tr><td class="paramname">timeout</td><td>Timeout to wait. The zero waits forever. </td></tr>
</table>
</dd>
</dl>
</div>
</div>
</div>
<!--- window showing the filter options -->
<div id="MSearchSelectWindow"
onmouseover="return searchBox.OnSearchSelectShow()"
onmouseout="return searchBox.OnSearchSelectHide()"
onkeydown="return searchBox.OnSearchSelectKey(event)">
<a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(0)"><span class="SelectionMark"> </span>All</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(1)"><span class="SelectionMark"> </span>Data Structures</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(2)"><span class="SelectionMark"> </span>Namespaces</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(3)"><span class="SelectionMark"> </span>Files</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(4)"><span class="SelectionMark"> </span>Functions</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(5)"><span class="SelectionMark"> </span>Variables</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(6)"><span class="SelectionMark"> </span>Typedefs</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(7)"><span class="SelectionMark"> </span>Enumerations</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(8)"><span class="SelectionMark"> </span>Enumerator</a><a class="SelectItem" href="javascript:void(0)" onclick="searchBox.OnSelectItem(9)"><span class="SelectionMark"> </span>Defines</a></div>
<!-- iframe showing the search results (closed by default) -->
<div id="MSearchResultsWindow">
<iframe src="" frameborder="0"
name="MSearchResults" id="MSearchResults">
</iframe>
</div>
<hr class="footer"/><address class="footer"><small>Generated on Tue Feb 8 2011 for Apache Portable Runtime by 
<a href="http://www.doxygen.org/index.html">
<img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.7.3 </small></address>
</body>
</html>
