| 1 |
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> |
| 2 |
<html><head><meta http-equiv="Content-Type" content="text/html;charset=iso-8859-1"> |
| 3 |
<title>PEAK Library: Garbage collector</title> |
| 4 |
<link href="doxygen.css" rel="stylesheet" type="text/css"> |
| 5 |
</head><body> |
| 6 |
<!-- Generated by Doxygen 1.3.5 --> |
| 7 |
<div class="qindex"><a class="qindex" href="index.html">Main Page</a> | <a class="qindex" href="modules.html">Modules</a> | <a class="qindex" href="annotated.html">Data Structures</a> | <a class="qindex" href="functions.html">Data Fields</a></div> |
| 8 |
<h1>Garbage collector</h1><hr><a name="_details"></a><h2>Detailed Description</h2> |
| 9 |
<dl compact><dt><b></b></dt><dd>In brief: this module adds a feature to delay the destruction of pointers of different sizes, thus allowing the application to reuse some pointers not really deleted yet. See the <code>mem_pool</code> module for another type of allocation optimization feature.</dd></dl> |
| 10 |
<dl compact><dt><b></b></dt><dd>A simple garbage collector (with explicit collection) which provides asynchronous deletion. It is probably only useful when an application could avoid to recreate the same objects, when all objects are not of the same size. If it's better for you to just keep them a few seconds or minutes before really delete them, in case you want to reuse them, so this module is probably for you. When it's time to really delete an object, the library calls your callback: if the object has been reused since, just ignore the call... or really delete it otherwise.</dd></dl> |
| 11 |
<dl compact><dt><b></b></dt><dd>This module has been created in order to optimize allocations of IRC channels, which are allocated structures of different sizes (different names) and commonly deleted and re-allocated just after (part/join of an empty channel). I am not sure it will suit for something else.</dd></dl> |
| 12 |
<dl compact><dt><b></b></dt><dd>Usage is very easy: initialize a garbage collector object with <a class="el" href="group__garbage.html#ga9">peak_garbage_create()</a> providing a generic deletion callback for all collected objects, then call <a class="el" href="group__garbage.html#ga10">peak_garbage_collect()</a> for each object you want to delete using the collector. The objects will be automatically deleted (you shouldn't predict the deletion, as the frequency is only a hint - note it's usually less because all collected objects are always deleted at the same time). If needed, you can force all objects deletion with the <a class="el" href="group__garbage.html#ga12">peak_garbage_vacuum()</a> function. </dd></dl> |
| 13 |
|
| 14 |
<p> |
| 15 |
<table border=0 cellpadding=0 cellspacing=0> |
| 16 |
<tr><td></td></tr> |
| 17 |
<tr><td colspan=2><br><h2>Typedefs</h2></td></tr> |
| 18 |
<tr><td class="memItemLeft" nowrap align=right valign=top><a class="anchor" name="ga0" doxytag="garbage::peak_garbage" ></a> |
| 19 |
typedef __peak_garbage * </td><td class="memItemRight" valign=bottom><a class="el" href="group__garbage.html#ga0">peak_garbage</a></td></tr> |
| 20 |
|
| 21 |
<tr><td class="mdescLeft"> </td><td class="mdescRight">Opaque garbage collector pointer type. <br><br></td></tr> |
| 22 |
<tr><td class="memItemLeft" nowrap align=right valign=top><a class="anchor" name="ga1" doxytag="garbage::peak_garbage_callback" ></a> |
| 23 |
typedef void(* </td><td class="memItemRight" valign=bottom><a class="el" href="group__garbage.html#ga1">peak_garbage_callback</a> )(<a class="el" href="group__garbage.html#ga0">peak_garbage</a> g, void *ptr, void *context)</td></tr> |
| 24 |
|
| 25 |
<tr><td class="mdescLeft"> </td><td class="mdescRight">Deletion's callback definition. <br><br></td></tr> |
| 26 |
<tr><td colspan=2><br><h2>Functions</h2></td></tr> |
| 27 |
<tr><td class="memItemLeft" nowrap align=right valign=top><a class="el" href="group__garbage.html#ga0">peak_garbage</a> </td><td class="memItemRight" valign=bottom><a class="el" href="group__garbage.html#ga2">peak_garbage_create</a> (int max_ptrs, double frequency, <a class="el" href="group__task__common.html#ga0">peak_task</a> task, <a class="el" href="group__garbage.html#ga1">peak_garbage_callback</a> callout, void *context)</td></tr> |
| 28 |
|
| 29 |
<tr><td class="mdescLeft"> </td><td class="mdescRight">Create a garbage object. <a href="#ga2"></a><br><br></td></tr> |
| 30 |
<tr><td class="memItemLeft" nowrap align=right valign=top>void </td><td class="memItemRight" valign=bottom><a class="el" href="group__garbage.html#ga3">peak_garbage_collect</a> (<a class="el" href="group__garbage.html#ga0">peak_garbage</a> g, void *ptr)</td></tr> |
| 31 |
|
| 32 |
<tr><td class="mdescLeft"> </td><td class="mdescRight">Collect a pointer and schedules the garbage's task for deletion. <a href="#ga3"></a><br><br></td></tr> |
| 33 |
<tr><td class="memItemLeft" nowrap align=right valign=top>int </td><td class="memItemRight" valign=bottom><a class="el" href="group__garbage.html#ga4">peak_garbage_get_collected_count</a> (<a class="el" href="group__garbage.html#ga0">peak_garbage</a> g)</td></tr> |
| 34 |
|
| 35 |
<tr><td class="mdescLeft"> </td><td class="mdescRight">Get the current number of pointers collected for deletion. <a href="#ga4"></a><br><br></td></tr> |
| 36 |
<tr><td class="memItemLeft" nowrap align=right valign=top>void </td><td class="memItemRight" valign=bottom><a class="el" href="group__garbage.html#ga5">peak_garbage_vacuum</a> (<a class="el" href="group__garbage.html#ga0">peak_garbage</a> g)</td></tr> |
| 37 |
|
| 38 |
<tr><td class="mdescLeft"> </td><td class="mdescRight">Perform manual vacuuming. <a href="#ga5"></a><br><br></td></tr> |
| 39 |
</table> |
| 40 |
<hr><h2>Function Documentation</h2> |
| 41 |
<a class="anchor" name="ga3" doxytag="garbage.h::peak_garbage_collect" ></a><p> |
| 42 |
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0"> |
| 43 |
<tr> |
| 44 |
<td class="mdRow"> |
| 45 |
<table cellpadding="0" cellspacing="0" border="0"> |
| 46 |
<tr> |
| 47 |
<td class="md" nowrap valign="top"> void peak_garbage_collect </td> |
| 48 |
<td class="md" valign="top">( </td> |
| 49 |
<td class="md" nowrap valign="top"><a class="el" href="group__garbage.html#ga0">peak_garbage</a> </td> |
| 50 |
<td class="mdname" nowrap> <em>g</em>, </td> |
| 51 |
</tr> |
| 52 |
<tr> |
| 53 |
<td></td> |
| 54 |
<td></td> |
| 55 |
<td class="md" nowrap>void * </td> |
| 56 |
<td class="mdname" nowrap> <em>ptr</em></td> |
| 57 |
</tr> |
| 58 |
<tr> |
| 59 |
<td></td> |
| 60 |
<td class="md">) </td> |
| 61 |
<td class="md" colspan="2"></td> |
| 62 |
</tr> |
| 63 |
|
| 64 |
</table> |
| 65 |
</td> |
| 66 |
</tr> |
| 67 |
</table> |
| 68 |
<table cellspacing=5 cellpadding=0 border=0> |
| 69 |
<tr> |
| 70 |
<td> |
| 71 |
|
| 72 |
</td> |
| 73 |
<td> |
| 74 |
|
| 75 |
<p> |
| 76 |
Collect a pointer and schedules the garbage's task for deletion. |
| 77 |
<p> |
| 78 |
Guaranteed O(1) unless <em>max_ptrs</em> is reached.<p> |
| 79 |
<dl compact><dt><b>Parameters:</b></dt><dd> |
| 80 |
<table border="0" cellspacing="2" cellpadding="0"> |
| 81 |
<tr><td valign=top><em>g</em> </td><td>The garbage object reference. </td></tr> |
| 82 |
<tr><td valign=top><em>ptr</em> </td><td>Pointer to collect for deletion. </td></tr> |
| 83 |
</table> |
| 84 |
</dl> |
| 85 |
</td> |
| 86 |
</tr> |
| 87 |
</table> |
| 88 |
<a class="anchor" name="ga2" doxytag="garbage.h::peak_garbage_create" ></a><p> |
| 89 |
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0"> |
| 90 |
<tr> |
| 91 |
<td class="mdRow"> |
| 92 |
<table cellpadding="0" cellspacing="0" border="0"> |
| 93 |
<tr> |
| 94 |
<td class="md" nowrap valign="top"> <a class="el" href="group__garbage.html#ga0">peak_garbage</a> peak_garbage_create </td> |
| 95 |
<td class="md" valign="top">( </td> |
| 96 |
<td class="md" nowrap valign="top">int </td> |
| 97 |
<td class="mdname" nowrap> <em>max_ptrs</em>, </td> |
| 98 |
</tr> |
| 99 |
<tr> |
| 100 |
<td></td> |
| 101 |
<td></td> |
| 102 |
<td class="md" nowrap>double </td> |
| 103 |
<td class="mdname" nowrap> <em>frequency</em>, </td> |
| 104 |
</tr> |
| 105 |
<tr> |
| 106 |
<td></td> |
| 107 |
<td></td> |
| 108 |
<td class="md" nowrap><a class="el" href="group__task__common.html#ga0">peak_task</a> </td> |
| 109 |
<td class="mdname" nowrap> <em>task</em>, </td> |
| 110 |
</tr> |
| 111 |
<tr> |
| 112 |
<td></td> |
| 113 |
<td></td> |
| 114 |
<td class="md" nowrap><a class="el" href="group__garbage.html#ga1">peak_garbage_callback</a> </td> |
| 115 |
<td class="mdname" nowrap> <em>callout</em>, </td> |
| 116 |
</tr> |
| 117 |
<tr> |
| 118 |
<td></td> |
| 119 |
<td></td> |
| 120 |
<td class="md" nowrap>void * </td> |
| 121 |
<td class="mdname" nowrap> <em>context</em></td> |
| 122 |
</tr> |
| 123 |
<tr> |
| 124 |
<td></td> |
| 125 |
<td class="md">) </td> |
| 126 |
<td class="md" colspan="2"></td> |
| 127 |
</tr> |
| 128 |
|
| 129 |
</table> |
| 130 |
</td> |
| 131 |
</tr> |
| 132 |
</table> |
| 133 |
<table cellspacing=5 cellpadding=0 border=0> |
| 134 |
<tr> |
| 135 |
<td> |
| 136 |
|
| 137 |
</td> |
| 138 |
<td> |
| 139 |
|
| 140 |
<p> |
| 141 |
Create a garbage object. |
| 142 |
<p> |
| 143 |
<dl compact><dt><b>Parameters:</b></dt><dd> |
| 144 |
<table border="0" cellspacing="2" cellpadding="0"> |
| 145 |
<tr><td valign=top><em>max_ptrs</em> </td><td>Max pointers that the garbage object can collect at the same time. Must be strictly positive. If reached, a vacuuming is performed and the object properly collected. </td></tr> |
| 146 |
<tr><td valign=top><em>frequency</em> </td><td>Frequency hint in seconds at which you want to do the vacuuming (deletions), it's usually less because when vacuuming the callback is called for all objects already collected. </td></tr> |
| 147 |
<tr><td valign=top><em>task</em> </td><td>Task to schedule, can be <code>NULL</code> to use current task. </td></tr> |
| 148 |
<tr><td valign=top><em>callout</em> </td><td>A pointer to your deletion callback function which is triggered when automatic of manual vacuuming. </td></tr> |
| 149 |
<tr><td valign=top><em>context</em> </td><td>An extra application-defined pointer that will be passed to your garbage callback function.</td></tr> |
| 150 |
</table> |
| 151 |
</dl> |
| 152 |
<dl compact><dt><b>Returns:</b></dt><dd>A newly allocated <code>peak_garbage</code> reference or <code>NULL</code> if the object cannot be created. </dd></dl> |
| 153 |
</td> |
| 154 |
</tr> |
| 155 |
</table> |
| 156 |
<a class="anchor" name="ga4" doxytag="garbage.h::peak_garbage_get_collected_count" ></a><p> |
| 157 |
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0"> |
| 158 |
<tr> |
| 159 |
<td class="mdRow"> |
| 160 |
<table cellpadding="0" cellspacing="0" border="0"> |
| 161 |
<tr> |
| 162 |
<td class="md" nowrap valign="top"> int peak_garbage_get_collected_count </td> |
| 163 |
<td class="md" valign="top">( </td> |
| 164 |
<td class="md" nowrap valign="top"><a class="el" href="group__garbage.html#ga0">peak_garbage</a> </td> |
| 165 |
<td class="mdname1" valign="top" nowrap> <em>g</em> </td> |
| 166 |
<td class="md" valign="top"> ) </td> |
| 167 |
<td class="md" nowrap></td> |
| 168 |
</tr> |
| 169 |
|
| 170 |
</table> |
| 171 |
</td> |
| 172 |
</tr> |
| 173 |
</table> |
| 174 |
<table cellspacing=5 cellpadding=0 border=0> |
| 175 |
<tr> |
| 176 |
<td> |
| 177 |
|
| 178 |
</td> |
| 179 |
<td> |
| 180 |
|
| 181 |
<p> |
| 182 |
Get the current number of pointers collected for deletion. |
| 183 |
<p> |
| 184 |
<dl compact><dt><b>Parameters:</b></dt><dd> |
| 185 |
<table border="0" cellspacing="2" cellpadding="0"> |
| 186 |
<tr><td valign=top><em>g</em> </td><td>The garbage object reference.</td></tr> |
| 187 |
</table> |
| 188 |
</dl> |
| 189 |
<dl compact><dt><b>Returns:</b></dt><dd>Collected pointers count. </dd></dl> |
| 190 |
</td> |
| 191 |
</tr> |
| 192 |
</table> |
| 193 |
<a class="anchor" name="ga5" doxytag="garbage.h::peak_garbage_vacuum" ></a><p> |
| 194 |
<table class="mdTable" width="100%" cellpadding="2" cellspacing="0"> |
| 195 |
<tr> |
| 196 |
<td class="mdRow"> |
| 197 |
<table cellpadding="0" cellspacing="0" border="0"> |
| 198 |
<tr> |
| 199 |
<td class="md" nowrap valign="top"> void peak_garbage_vacuum </td> |
| 200 |
<td class="md" valign="top">( </td> |
| 201 |
<td class="md" nowrap valign="top"><a class="el" href="group__garbage.html#ga0">peak_garbage</a> </td> |
| 202 |
<td class="mdname1" valign="top" nowrap> <em>g</em> </td> |
| 203 |
<td class="md" valign="top"> ) </td> |
| 204 |
<td class="md" nowrap></td> |
| 205 |
</tr> |
| 206 |
|
| 207 |
</table> |
| 208 |
</td> |
| 209 |
</tr> |
| 210 |
</table> |
| 211 |
<table cellspacing=5 cellpadding=0 border=0> |
| 212 |
<tr> |
| 213 |
<td> |
| 214 |
|
| 215 |
</td> |
| 216 |
<td> |
| 217 |
|
| 218 |
<p> |
| 219 |
Perform manual vacuuming. |
| 220 |
<p> |
| 221 |
<dl compact><dt><b>Parameters:</b></dt><dd> |
| 222 |
<table border="0" cellspacing="2" cellpadding="0"> |
| 223 |
<tr><td valign=top><em>g</em> </td><td>The garbage object reference. </td></tr> |
| 224 |
</table> |
| 225 |
</dl> |
| 226 |
</td> |
| 227 |
</tr> |
| 228 |
</table> |
| 229 |
<hr size="1"><address style="align: right;"><small>Generated on Sat Jan 17 21:41:54 2004 for the PEAK Library by |
| 230 |
<a href="http://www.doxygen.org/index.html"> |
| 231 |
<img src="doxygen.png" alt="doxygen" align="middle" border="0" > |
| 232 |
</a></small> <a href="http://sourceforge.net"><img src="http://sourceforge.net/sflogo.php?group_id=98146&type=1" width="88" height="31" align="middle" border="0" alt="SourceForge.net Logo" /></a></address> |
| 233 |
</body> |
| 234 |
</html> |
| 235 |
|
