libxml2/doc/xmlmem.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/1999/REC-html401-19991224/loose.dtd">
   2 <html>
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   5 <link rel="SHORTCUT ICON" href="/favicon.ico">
   6 <style type="text/css"><!--
   7 TD {font-family: Verdana,Arial,Helvetica}
   8 BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
   9 H1 {font-family: Verdana,Arial,Helvetica}
  10 H2 {font-family: Verdana,Arial,Helvetica}
  11 H3 {font-family: Verdana,Arial,Helvetica}
  12 A:link, A:visited, A:active { text-decoration: underline }
  13 --></style>
  14 <title>Memory Management</title>
  15 </head>
  16 <body bgcolor="#8b7765" text="#000000" link="#000000" vlink="#000000">
  17 <table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr>
  18 <td width="180">
  19 <a href="http://www.gnome.org/"><img src="gnome2.png" alt="Gnome2 Logo"></a><a href="http://www.w3.org/Status"><img src="w3c.png" alt="W3C Logo"></a><a href="http://www.redhat.com/"><img src="redhat.gif" alt="Red Hat Logo"></a><div align="left"><a href="http://xmlsoft.org/"><img src="Libxml2-Logo-180x168.gif" alt="Made with Libxml2 Logo"></a></div>
  20 </td>
  21 <td><table border="0" width="90%" cellpadding="2" cellspacing="0" align="center" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3" bgcolor="#fffacd"><tr><td align="center">
  22 <h1>The XML C library for Gnome</h1>
  23 <h2>Memory Management</h2>
  24 </td></tr></table></td></tr></table></td>
  25 </tr></table>
  26 <table border="0" cellpadding="4" cellspacing="0" width="100%" align="center"><tr><td bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="2" width="100%"><tr>
  27 <td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td>
  28 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  29 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Main Menu</b></center></td></tr>
  30 <tr><td bgcolor="#fffacd">
  31 <form action="search.php" enctype="application/x-www-form-urlencoded" method="GET">
  32 <input name="query" type="TEXT" size="20" value=""><input name="submit" type="submit" value="Search ...">
  33 </form>
  34 <ul>
  35 <li><a href="index.html">Home</a></li>
  36 <li><a href="intro.html">Introduction</a></li>
  37 <li><a href="FAQ.html">FAQ</a></li>
  38 <li><a href="docs.html">Documentation</a></li>
  39 <li><a href="bugs.html">Reporting bugs and getting help</a></li>
  40 <li><a href="help.html">How to help</a></li>
  41 <li><a href="downloads.html">Downloads</a></li>
  42 <li><a href="news.html">News</a></li>
  43 <li><a href="XMLinfo.html">XML</a></li>
  44 <li><a href="XSLT.html">XSLT</a></li>
  45 <li><a href="python.html">Python and bindings</a></li>
  46 <li><a href="architecture.html">libxml architecture</a></li>
  47 <li><a href="tree.html">The tree output</a></li>
  48 <li><a href="interface.html">The SAX interface</a></li>
  49 <li><a href="xmldtd.html">Validation &amp; DTDs</a></li>
  50 <li><a href="xmlmem.html">Memory Management</a></li>
  51 <li><a href="encoding.html">Encodings support</a></li>
  52 <li><a href="xmlio.html">I/O Interfaces</a></li>
  53 <li><a href="catalog.html">Catalog support</a></li>
  54 <li><a href="library.html">The parser interfaces</a></li>
  55 <li><a href="entities.html">Entities or no entities</a></li>
  56 <li><a href="namespaces.html">Namespaces</a></li>
  57 <li><a href="upgrade.html">Upgrading 1.x code</a></li>
  58 <li><a href="threads.html">Thread safety</a></li>
  59 <li><a href="DOM.html">DOM Principles</a></li>
  60 <li><a href="example.html">A real example</a></li>
  61 <li><a href="contribs.html">Contributions</a></li>
  62 <li><a href="xmlreader.html">The Reader Interface</a></li>
  63 <li><a href="tutorial/index.html">Tutorial</a></li>
  64 <li><a href="guidelines.html">XML Guidelines</a></li>
  65 <li>
  66 <a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a>
  67 </li>
  68 </ul>
  69 </td></tr>
  70 </table>
  71 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  72 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr>
  73 <tr><td bgcolor="#fffacd"><ul>
  74 <li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li>
  75 <li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li>
  76 <li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li>
  77 <li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li>
  78 <li><a href="ftp://xmlsoft.org/">FTP</a></li>
  79 <li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li>
  80 <li><a href="http://garypennington.net/libxml2/">Solaris binaries</a></li>
  81 <li><a href="http://www.zveno.com/open_source/libxml2xslt.html">MacOsX binaries</a></li>
  82 <li><a href="http://sourceforge.net/projects/libxml2-pas/">Pascal bindings</a></li>
  83 <li><a href="http://bugzilla.gnome.org/buglist.cgi?product=libxml&amp;product=libxml2">Bug Tracker</a></li>
  84 </ul></td></tr>
  85 </table>
  86 <table width="100%" border="0" cellspacing="1" cellpadding="3">
  87 <tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr>
  88 <tr><td bgcolor="#fffacd"><ul>
  89 <li><a href="APIchunk0.html">Alphabetic</a></li>
  90 <li><a href="APIconstructors.html">Constructors</a></li>
  91 <li><a href="APIfunctions.html">Functions/Types</a></li>
  92 <li><a href="APIfiles.html">Modules</a></li>
  93 <li><a href="APIsymbols.html">Symbols</a></li>
  94 </ul></td></tr>
  95 </table>
  96 </td></tr></table></td>
  97 <td valign="top" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%"><tr><td><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table border="0" cellpadding="3" cellspacing="1" width="100%"><tr><td bgcolor="#fffacd">
  98 <p>Table of Content:</p>
  99 <ol>
 100 <li><a href="#General3">General overview</a></li>
 101   <li><a href="#setting">Setting libxml set of memory routines</a></li>
 102   <li><a href="#cleanup">Cleaning up after parsing</a></li>
 103   <li><a href="#Debugging">Debugging routines</a></li>
 104   <li><a href="#General4">General memory requirements</a></li>
 105 </ol>
 106 <h3><a name="General3">General overview</a></h3>
 107 <p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>
 108 provides the interfaces to the libxml memory system:</p>
 109 <ul>
 110 <li>libxml does not use the libc memory allocator directly but xmlFree(),
 111     xmlMalloc() and xmlRealloc()</li>
 112   <li>those routines can be reallocated to a specific set of routine, by
 113     default the libc ones i.e. free(), malloc() and realloc()</li>
 114   <li>the xmlmemory.c module includes a set of debugging routine</li>
 115 </ul>
 116 <h3><a name="setting">Setting libxml set of memory routines</a></h3>
 117 <p>It is sometimes useful to not use the default memory allocator, either for
 118 debugging, analysis or to implement a specific behaviour on memory management
 119 (like on embedded systems). Two function calls are available to do so:</p>
 120 <ul>
 121 <li>
 122 <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet
 123     ()</a> which return the current set of functions in use by the parser</li>
 124   <li>
 125 <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>
 126     which allow to set up a new set of memory allocation functions</li>
 127 </ul>
 128 <p>Of course a call to xmlMemSetup() should probably be done before calling
 129 any other libxml routines (unless you are sure your allocations routines are
 130 compatibles).</p>
 131 <h3><a name="cleanup">Cleaning up after parsing</a></h3>
 132 <p>Libxml is not stateless, there is a few set of memory structures needing
 133 allocation before the parser is fully functional (some encoding structures
 134 for example). This also mean that once parsing is finished there is a tiny
 135 amount of memory (a few hundred bytes) which can be recollected if you don't
 136 reuse the parser immediately:</p>
 137 <ul>
 138 <li>
 139 <a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser
 140     ()</a> is a centralized routine to free the parsing states. Note that it
 141     won't deallocate any produced tree if any (use the xmlFreeDoc() and
 142     related routines for this).</li>
 143   <li>
 144 <a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser
 145     ()</a> is the dual routine allowing to preallocate the parsing state
 146     which can be useful for example to avoid initialization reentrancy
 147     problems when using libxml in multithreaded applications</li>
 148 </ul>
 149 <p>Generally xmlCleanupParser() is safe, if needed the state will be rebuild
 150 at the next invocation of parser routines, but be careful of the consequences
 151 in multithreaded applications.</p>
 152 <h3><a name="Debugging">Debugging routines</a></h3>
 153 <p>When configured using --with-mem-debug flag (off by default), libxml uses
 154 a set of memory allocation debugging routines keeping track of all allocated
 155 blocks and the location in the code where the routine was called. A couple of
 156 other debugging routines allow to dump the memory allocated infos to a file
 157 or call a specific routine when a given block number is allocated:</p>
 158 <ul>
 159 <li>
 160 <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a>
 161     <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>
 162     and <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>
 163     are the memory debugging replacement allocation routines</li>
 164   <li>
 165 <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump
 166     ()</a> dumps all the informations about the allocated memory block lefts
 167     in the <code>.memdump</code> file</li>
 168 </ul>
 169 <p>When developing libxml memory debug is enabled, the tests programs call
 170 xmlMemoryDump () and the &quot;make test&quot; regression tests will check for any
 171 memory leak during the full regression test sequence, this helps a lot
 172 ensuring that libxml  does not leak memory and bullet proof memory
 173 allocations use (some libc implementations are known to be far too permissive
 174 resulting in major portability problems!).</p>
 175 <p>If the .memdump reports a leak, it displays the allocation function and
 176 also tries to give some informations about the content and structure of the
 177 allocated blocks left. This is sufficient in most cases to find the culprit,
 178 but not always. Assuming the allocation problem is reproducible, it is
 179 possible to find more easily:</p>
 180 <ol>
 181 <li>write down the block number xxxx not allocated</li>
 182   <li>export the environment variable XML_MEM_BREAKPOINT=xxxx , the easiest
 183     when using GDB is to simply give the command
 184     <p><code>set environment XML_MEM_BREAKPOINT xxxx</code></p>
 185     <p>before running the program.</p>
 186   </li>
 187   <li>run the program under a debugger and set a breakpoint on
 188     xmlMallocBreakpoint() a specific function called when this precise block
 189     is allocated</li>
 190   <li>when the breakpoint is reached you can then do a fine analysis of the
 191     allocation an step  to see the condition resulting in the missing
 192     deallocation.</li>
 193 </ol>
 194 <p>I used to use a commercial tool to debug libxml memory problems but after
 195 noticing that it was not detecting memory leaks that simple mechanism was
 196 used and proved extremely efficient until now. Lately I have also used <a href="http://developer.kde.org/~sewardj/">valgrind</a> with quite some
 197 success, it is tied to the i386 architecture since it works by emulating the
 198 processor and instruction set, it is slow but  extremely efficient, i.e. it
 199 spot memory usage errors in a very precise way.</p>
 200 <h3><a name="General4">General memory requirements</a></h3>
 201 <p>How much libxml memory require ? It's hard to tell in average it depends
 202 of a number of things:</p>
 203 <ul>
 204 <li>the parser itself should work  in a fixed amount of memory, except for
 205     information maintained about the stacks of names and  entities locations.
 206     The I/O and encoding handlers will probably account for a few KBytes.
 207     This is true for both the XML and HTML parser (though the HTML parser
 208     need more state).</li>
 209   <li>If you are generating the DOM tree then memory requirements will grow
 210     nearly linear with the size of the data. In general for a balanced
 211     textual document the internal memory requirement is about 4 times the
 212     size of the UTF8 serialization of this document (example the XML-1.0
 213     recommendation is a bit more of 150KBytes and takes 650KBytes of main
 214     memory when parsed). Validation will add a amount of memory required for
 215     maintaining the external Dtd state which should be linear with the
 216     complexity of the content model defined by the Dtd</li>
 217   <li>If you don't care about the advanced features of libxml like
 218     validation, DOM, XPath or XPointer, but really need to work fixed memory
 219     requirements, then the SAX interface should be used.</li>
 220 </ul>
 221 <p></p>
 222 <p><a href="bugs.html">Daniel Veillard</a></p>
 223 </td></tr></table></td></tr></table></td></tr></table></td>
 224 </tr></table></td></tr></table>
 225 </body>
 226 </html>