libxml2/doc/xmlmem.html

<?xml version="1.0" encoding="UTF-8"?>
<!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/html; charset=UTF-8" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">
TD {font-family: Verdana,Arial,Helvetica}
BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}
H1 {font-family: Verdana,Arial,Helvetica}
H2 {font-family: Verdana,Arial,Helvetica}
H3 {font-family: Verdana,Arial,Helvetica}
A:link, A:visited, A:active { text-decoration: underline }
</style><title>Memory Management</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><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></td><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"><h1>The XML C parser and toolkit of Gnome</h1><h2>Memory Management</h2></td></tr></table></td></tr></table></td></tr></table><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><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Developer Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html" style="font-weight:bold">Main Menu</a></li><li><a href="html/index.html" style="font-weight:bold">Reference Manual</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="tutorial/index.html">Tutorial</a></li><li><a href="xmlreader.html">The Reader Interface</a></li><li><a href="ChangeLog.html">ChangeLog</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="python.html">Python and bindings</a></li><li><a href="architecture.html">libxml2 architecture</a></li><li><a href="tree.html">The tree output</a></li><li><a href="interface.html">The SAX interface</a></li><li><a href="xmlmem.html">Memory Management</a></li><li><a href="xmlio.html">I/O Interfaces</a></li><li><a href="library.html">The parser interfaces</a></li><li><a href="entities.html">Entities or no entities</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="upgrade.html">Upgrading 1.x code</a></li><li><a href="threads.html">Thread safety</a></li><li><a href="DOM.html">DOM Principles</a></li><li><a href="example.html">A real example</a></li><li><a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="APIchunk0.html">Alphabetic</a></li><li><a href="APIconstructors.html">Constructors</a></li><li><a href="APIfunctions.html">Functions/Types</a></li><li><a href="APIfiles.html">Modules</a></li><li><a href="APIsymbols.html">Symbols</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://opencsw.org/packages/libxml2">Sola
  <li><a href="#General3">General overview</a></li>
  <li><a href="#setting">Setting libxml2 set of memory routines</a></li>
  <li><a href="#cleanup">Cleaning up after using the library</a></li>
  <li><a href="#Debugging">Debugging routines</a></li>
  <li><a href="#General4">General memory requirements</a></li>
  <li><a href="#Compacting">Returning memory to the kernel</a></li>
</ol><h3><a name="General3" id="General3">General overview</a></h3><p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>
provides the interfaces to the libxml2 memory system:</p><ul>
  <li>libxml2 does not use the libc memory allocator directly but xmlFree(),
    xmlMalloc() and xmlRealloc()</li>
  <li>those routines can be reallocated to a specific set of routine, by
    default the libc ones i.e. free(), malloc() and realloc()</li>
  <li>the xmlmemory.c module includes a set of debugging routine</li>
</ul><h3><a name="setting" id="setting">Setting libxml2 set of memory routines</a></h3><p>It is sometimes useful to not use the default memory allocator, either for
debugging, analysis or to implement a specific behaviour on memory management
(like on embedded systems). Two function calls are available to do so:</p><ul>
  <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet
    ()</a> which return the current set of functions in use by the parser</li>
  <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>
    which allow to set up a new set of memory allocation functions</li>
</ul><p>Of course a call to xmlMemSetup() should probably be done before calling
any other libxml2 routines (unless you are sure your allocations routines are
compatibles).</p><h3><a name="cleanup" id="cleanup">Cleaning up after using the library</a></h3><p>Libxml2 is not stateless, there is a few set of memory structures needing
allocation before the parser is fully functional (some encoding structures
for example). This also mean that once parsing is finished there is a tiny
amount of memory (a few hundred bytes) which can be recollected if you don't
reuse the library or any document built with it:</p><ul>
  <li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser
    ()</a> is a centralized routine to free the library state and data. Note
    that it won't deallocate any produced tree if any (use the xmlFreeDoc()
    and related routines for this). This should be called only when the library
    is not used anymore.</li>
  <li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser
    ()</a> is the dual routine allowing to preallocate the parsing state
    which can be useful for example to avoid initialization reentrancy
    problems when using libxml2 in multithreaded applications</li>
</ul><p>Generally xmlCleanupParser() is safe assuming no parsing is ongoing and
no document is still being used, if needed the state will be rebuild at the
next invocation of parser routines (or by xmlInitParser()), but be careful
of the consequences in multithreaded applications.</p><h3><a name="Debugging" id="Debugging">Debugging routines</a></h3><p>When configured using --with-mem-debug flag (off by default), libxml2 uses
a set of memory allocation debugging routines keeping track of all allocated
blocks and the location in the code where the routine was called. A couple of
other debugging routines allow to dump the memory allocated infos to a file
or call a specific routine when a given block number is allocated:</p><ul>
  <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a>
    <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>
    and <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>
    are the memory debugging replacement allocation routines</li>
  <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump
    ()</a> dumps all the information about the allocated memory block lefts
    in the <code>.memdump</code> file</li>
</ul><p>When developing libxml2 memory debug is enabled, the tests programs call
xmlMemoryDump () and the "make test" regression tests will check for any
memory leak during the full regression test sequence, this helps a lot
ensuring that libxml2  does not leak memory and bullet proof memory
allocations use (some libc implementations are known to be far too permissive
resulting in major portability problems!).</p><p>If the .memdump reports a leak, it displays the allocation function and
also tries to give some information about the content and structure of the
allocated blocks left. This is sufficient in most cases to find the culprit,
but not always. Assuming the allocation problem is reproducible, it is
possible to find more easily:</p><ol>
  <li>write down the block number xxxx not allocated</li>
  <li>export the environment variable XML_MEM_BREAKPOINT=xxxx , the easiest
    when using GDB is to simply give the command
    <p><code>set environment XML_MEM_BREAKPOINT xxxx</code></p>
    <p>before running the program.</p>
  </li>
  <li>run the program under a debugger and set a breakpoint on
    xmlMallocBreakpoint() a specific function called when this precise block
    is allocated</li>
  <li>when the breakpoint is reached you can then do a fine analysis of the
    allocation an step  to see the condition resulting in the missing
    deallocation.</li>
</ol><p>I used to use a commercial tool to debug libxml2 memory problems but after
noticing that it was not detecting memory leaks that simple mechanism was
used and proved extremely efficient until now. Lately I have also used <a href="http://developer.kde.org/~sewardj/">valgrind</a> with quite some
success, it is tied to the i386 architecture since it works by emulating the
processor and instruction set, it is slow but  extremely efficient, i.e. it
spot memory usage errors in a very precise way.</p><h3><a name="General4" id="General4">General memory requirements</a></h3><p>How much libxml2 memory require ? It's hard to tell in average it depends
of a number of things:</p><ul>
  <li>the parser itself should work  in a fixed amount of memory, except for
    information maintained about the stacks of names and  entities locations.
    The I/O and encoding handlers will probably account for a few KBytes.
    This is true for both the XML and HTML parser (though the HTML parser
    need more state).</li>
  <li>If you are generating the DOM tree then memory requirements will grow
    nearly linear with the size of the data. In general for a balanced
    textual document the internal memory requirement is about 4 times the
    size of the UTF8 serialization of this document (example the XML-1.0
    recommendation is a bit more of 150KBytes and takes 650KBytes of main
    memory when parsed). Validation will add a amount of memory required for
    maintaining the external Dtd state which should be linear with the
    complexity of the content model defined by the Dtd</li>
  <li>If you need to work with fixed memory requirements or don't need the
    full DOM tree then using the <a href="xmlreader.html">xmlReader
    interface</a> is probably the best way to proceed, it still allows to
    validate or operate on subset of the tree if needed.</li>
  <li>If you don't care about the advanced features of libxml2 like
    validation, DOM, XPath or XPointer, don't use entities, need to work with
    fixed memory requirements, and try to get the fastest parsing possible
    then the SAX interface should be used, but it has known restrictions.</li>
</ul><p></p><h3><a name="Compacting" id="Compacting">Returning memory to the kernel</a></h3><p>You may encounter that your process using libxml2 does not have a
reduced memory usage although you freed the trees. This is because
libxml2 allocates memory in a number of small chunks. When freeing one
of those chunks, the OS may decide that giving this little memory back
to the kernel will cause too much overhead and delay the operation. As
all chunks are this small, they get actually freed but not returned to
the kernel. On systems using glibc, there is a function call
"malloc_trim" from malloc.h which does this missing operation (note that
it is allowed to fail). Thus, after freeing your tree you may simply try
"malloc_trim(0);" to really get the memory back. If your OS does not
provide malloc_trim, try searching for a similar function.</p><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>
Fix web site encoding problems The encoding.html page was generated incorectly, revamp the input xml.html and convert the full XSLT chain to use and serve it as UTF-8 * doc/*: fix xml.html, update all stylesheets and regenerate 2010-09-30 13:58:22 +02:00			`<?xml version="1.0" encoding="UTF-8"?>`
updated the web site separated developers from common pages, made the * NEWS doc/.xsl doc/.html: updated the web site separated developers from common pages, made the transition to XHTML1, added validity checking to the makefile rules. Daniel 2003-04-26 22:29:54 +00:00			`<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">`
Fix web site encoding problems The encoding.html page was generated incorectly, revamp the input xml.html and convert the full XSLT chain to use and serve it as UTF-8 * doc/*: fix xml.html, update all stylesheets and regenerate 2010-09-30 13:58:22 +02:00			`<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /><link rel="SHORTCUT ICON" href="/favicon.ico" /><style type="text/css">`
Removed the CSS font size, Daniel 2002-02-21 14:46:29 +00:00			`TD {font-family: Verdana,Arial,Helvetica}`
			`BODY {font-family: Verdana,Arial,Helvetica; margin-top: 2em; margin-left: 0em; margin-right: 0em}`
			`H1 {font-family: Verdana,Arial,Helvetica}`
			`H2 {font-family: Verdana,Arial,Helvetica}`
			`H3 {font-family: Verdana,Arial,Helvetica}`
Finished reintegrating the docs and unifying the look, may still need a couple of pointers but looks fine now. valid.html si now merged in xmldtd.html. Overall cleanup, Daniel 2001-10-25 10:53:28 +00:00			`A:link, A:visited, A:active { text-decoration: underline }`
Rebuild docs 2019-09-30 17:34:32 +02:00			</style><title>Memory Management</title></head><body bgcolor="#8b7765" text="#000000" link="#a06060" vlink="#000000"><table border="0" width="100%" cellpadding="5" cellspacing="0" align="center"><tr><td width="120"><a href="http://swpat.ffii.org/"><img src="epatents.png" alt="Action against software patents" /></a></td><td width="180"><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></td><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"><h1>The XML C parser and toolkit of Gnome</h1><h2>Memory Management</h2></td></tr></table></td></tr></table></td></tr></table><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><td valign="top" width="200" bgcolor="#8b7765"><table border="0" cellspacing="0" cellpadding="1" width="100%" bgcolor="#000000"><tr><td><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Developer Menu</b></center></td></tr><tr><td bgcolor="#fffacd"><form action="search.php" enctype="application/x-www-form-urlencoded" method="get"><input name="query" type="text" size="20" value="" /><input name="submit" type="submit" value="Search ..." /></form><ul><li><a href="index.html" style="font-weight:bold">Main Menu</a></li><li><a href="html/index.html" style="font-weight:bold">Reference Manual</a></li><li><a href="examples/index.html" style="font-weight:bold">Code Examples</a></li><li><a href="guidelines.html">XML Guidelines</a></li><li><a href="tutorial/index.html">Tutorial</a></li><li><a href="xmlreader.html">The Reader Interface</a></li><li><a href="ChangeLog.html">ChangeLog</a></li><li><a href="XSLT.html">XSLT</a></li><li><a href="python.html">Python and bindings</a></li><li><a href="architecture.html">libxml2 architecture</a></li><li><a href="tree.html">The tree output</a></li><li><a href="interface.html">The SAX interface</a></li><li><a href="xmlmem.html">Memory Management</a></li><li><a href="xmlio.html">I/O Interfaces</a></li><li><a href="library.html">The parser interfaces</a></li><li><a href="entities.html">Entities or no entities</a></li><li><a href="namespaces.html">Namespaces</a></li><li><a href="upgrade.html">Upgrading 1.x code</a></li><li><a href="threads.html">Thread safety</a></li><li><a href="DOM.html">DOM Principles</a></li><li><a href="example.html">A real example</a></li><li><a href="xml.html">flat page</a>, <a href="site.xsl">stylesheet</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>API Indexes</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="APIchunk0.html">Alphabetic</a></li><li><a href="APIconstructors.html">Constructors</a></li><li><a href="APIfunctions.html">Functions/Types</a></li><li><a href="APIfiles.html">Modules</a></li><li><a href="APIsymbols.html">Symbols</a></li></ul></td></tr></table><table width="100%" border="0" cellspacing="1" cellpadding="3"><tr><td colspan="1" bgcolor="#eecfa1" align="center"><center><b>Related links</b></center></td></tr><tr><td bgcolor="#fffacd"><ul><li><a href="http://mail.gnome.org/archives/xml/">Mail archive</a></li><li><a href="http://xmlsoft.org/XSLT/">XSLT libxslt</a></li><li><a href="http://phd.cs.unibo.it/gdome2/">DOM gdome2</a></li><li><a href="http://www.aleksey.com/xmlsec/">XML-DSig xmlsec</a></li><li><a href="ftp://xmlsoft.org/">FTP</a></li><li><a href="http://www.zlatkovic.com/projects/libxml/">Windows binaries</a></li><li><a href="http://opencsw.org/packages/libxml2">Sola
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`<li><a href="#General3">General overview</a></li>`
Updates, changed libxml to libxml2 in a number of places, Daniel 2003-06-12 16:05:07 +00:00			`<li><a href="#setting">Setting libxml2 set of memory routines</a></li>`
trying to clarify even more the xmlCleanupParser() use and the memory * parser.c docs/*: trying to clarify even more the xmlCleanupParser() use and the memory documentation Daniel svn path=/trunk/; revision=3719 2008-03-31 08:27:07 +00:00			`<li><a href="#cleanup">Cleaning up after using the library</a></li>`
applied syntax patch from Rick Jones and rebuilt the web site. Daniel * doc/xml.html doc/*.html: applied syntax patch from Rick Jones and rebuilt the web site. Daniel 2002-07-24 23:47:05 +00:00			`<li><a href="#Debugging">Debugging routines</a></li>`
			`<li><a href="#General4">General memory requirements</a></li>`
added a small section on returning memory to the kernel by compacting the * doc/xml.html doc/xmlmem.html: added a small section on returning memory to the kernel by compacting the heap provided by Wolfram Sang Daniel svn path=/trunk/; revision=3682 2008-02-04 16:50:03 +00:00			`<li><a href="#Compacting">Returning memory to the kernel</a></li>`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`</ol><h3><a name="General3" id="General3">General overview</a></h3><p>The module <code><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>`
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`provides the interfaces to the libxml2 memory system:</p><ul>`
			`<li>libxml2 does not use the libc memory allocator directly but xmlFree(),`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`xmlMalloc() and xmlRealloc()</li>`
			`<li>those routines can be reallocated to a specific set of routine, by`
			`default the libc ones i.e. free(), malloc() and realloc()</li>`
applied syntax patch from Rick Jones and rebuilt the web site. Daniel * doc/xml.html doc/*.html: applied syntax patch from Rick Jones and rebuilt the web site. Daniel 2002-07-24 23:47:05 +00:00			`<li>the xmlmemory.c module includes a set of debugging routine</li>`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`</ul><h3><a name="setting" id="setting">Setting libxml2 set of memory routines</a></h3><p>It is sometimes useful to not use the default memory allocator, either for`
			`debugging, analysis or to implement a specific behaviour on memory management`
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`(like on embedded systems). Two function calls are available to do so:</p><ul>`
			`<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`()</a> which return the current set of functions in use by the parser</li>`
			`<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>`
			`which allow to set up a new set of memory allocation functions</li>`
			`</ul><p>Of course a call to xmlMemSetup() should probably be done before calling`
			`any other libxml2 routines (unless you are sure your allocations routines are`
trying to clarify even more the xmlCleanupParser() use and the memory * parser.c docs/*: trying to clarify even more the xmlCleanupParser() use and the memory documentation Daniel svn path=/trunk/; revision=3719 2008-03-31 08:27:07 +00:00			`compatibles).</p><h3><a name="cleanup" id="cleanup">Cleaning up after using the library</a></h3><p>Libxml2 is not stateless, there is a few set of memory structures needing`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`allocation before the parser is fully functional (some encoding structures`
			`for example). This also mean that once parsing is finished there is a tiny`
			`amount of memory (a few hundred bytes) which can be recollected if you don't`
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`reuse the library or any document built with it:</p><ul>`
			`<li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser`
trying to clarify even more the xmlCleanupParser() use and the memory * parser.c docs/*: trying to clarify even more the xmlCleanupParser() use and the memory documentation Daniel svn path=/trunk/; revision=3719 2008-03-31 08:27:07 +00:00			`()</a> is a centralized routine to free the library state and data. Note`
			`that it won't deallocate any produced tree if any (use the xmlFreeDoc()`
			`and related routines for this). This should be called only when the library`
			`is not used anymore.</li>`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`<li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser`
			`()</a> is the dual routine allowing to preallocate the parsing state`
			`which can be useful for example to avoid initialization reentrancy`
			`problems when using libxml2 in multithreaded applications</li>`
trying to clarify even more the xmlCleanupParser() use and the memory * parser.c docs/*: trying to clarify even more the xmlCleanupParser() use and the memory documentation Daniel svn path=/trunk/; revision=3719 2008-03-31 08:27:07 +00:00			`</ul><p>Generally xmlCleanupParser() is safe assuming no parsing is ongoing and`
			`no document is still being used, if needed the state will be rebuild at the`
			`next invocation of parser routines (or by xmlInitParser()), but be careful`
			`of the consequences in multithreaded applications.</p><h3><a name="Debugging" id="Debugging">Debugging routines</a></h3><p>When configured using --with-mem-debug flag (off by default), libxml2 uses`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`a set of memory allocation debugging routines keeping track of all allocated`
			`blocks and the location in the code where the routine was called. A couple of`
			`other debugging routines allow to dump the memory allocated infos to a file`
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`or call a specific routine when a given block number is allocated:</p><ul>`
			`<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a>`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`<a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>`
			`and <a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>`
			`are the memory debugging replacement allocation routines</li>`
			`<li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump`
Changed all references to libxml2 CVS over to the corresponding SVN. A few * doc/xml.html: Changed all references to libxml2 CVS over to the corresponding SVN. A few other spelling/grammar/links also changed. * doc/libxml2-api.xml, doc/*.html: Regenerated all docs. svn path=/trunk/; revision=3585 2007-02-15 20:41:02 +00:00			`()</a> dumps all the information about the allocated memory block lefts`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`in the <code>.memdump</code> file</li>`
			`</ul><p>When developing libxml2 memory debug is enabled, the tests programs call`
			`xmlMemoryDump () and the "make test" regression tests will check for any`
			`memory leak during the full regression test sequence, this helps a lot`
			`ensuring that libxml2 does not leak memory and bullet proof memory`
			`allocations use (some libc implementations are known to be far too permissive`
			`resulting in major portability problems!).</p><p>If the .memdump reports a leak, it displays the allocation function and`
Changed all references to libxml2 CVS over to the corresponding SVN. A few * doc/xml.html: Changed all references to libxml2 CVS over to the corresponding SVN. A few other spelling/grammar/links also changed. * doc/libxml2-api.xml, doc/*.html: Regenerated all docs. svn path=/trunk/; revision=3585 2007-02-15 20:41:02 +00:00			`also tries to give some information about the content and structure of the`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`allocated blocks left. This is sufficient in most cases to find the culprit,`
			`but not always. Assuming the allocation problem is reproducible, it is`
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`possible to find more easily:</p><ol>`
			`<li>write down the block number xxxx not allocated</li>`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`<li>export the environment variable XML_MEM_BREAKPOINT=xxxx , the easiest`
			`when using GDB is to simply give the command`
Hallski complained it could not be included by itself. Daniel * include/libxml/xmlIO.h: Hallski complained it could not be included by itself. Daniel 2002-04-12 21:03:34 +00:00			`<p><code>set environment XML_MEM_BREAKPOINT xxxx</code></p>`
applied syntax patch from Rick Jones and rebuilt the web site. Daniel * doc/xml.html doc/*.html: applied syntax patch from Rick Jones and rebuilt the web site. Daniel 2002-07-24 23:47:05 +00:00			`<p>before running the program.</p>`
			`</li>`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`<li>run the program under a debugger and set a breakpoint on`
			`xmlMallocBreakpoint() a specific function called when this precise block`
			`is allocated</li>`
			`<li>when the breakpoint is reached you can then do a fine analysis of the`
			`allocation an step to see the condition resulting in the missing`
			`deallocation.</li>`
			`</ol><p>I used to use a commercial tool to debug libxml2 memory problems but after`
			`noticing that it was not detecting memory leaks that simple mechanism was`
			`used and proved extremely efficient until now. Lately I have also used <a href="http://developer.kde.org/~sewardj/">valgrind</a> with quite some`
			`success, it is tied to the i386 architecture since it works by emulating the`
			`processor and instruction set, it is slow but extremely efficient, i.e. it`
			`spot memory usage errors in a very precise way.</p><h3><a name="General4" id="General4">General memory requirements</a></h3><p>How much libxml2 memory require ? It's hard to tell in average it depends`
Forgot to document 2.9.1 release, regenerate docs 2013-05-10 15:40:13 +08:00			`of a number of things:</p><ul>`
			`<li>the parser itself should work in a fixed amount of memory, except for`
Fix the breakages introduced by amaya, Daniel 2006-06-09 13:34:49 +00:00			`information maintained about the stacks of names and entities locations.`
			`The I/O and encoding handlers will probably account for a few KBytes.`
			`This is true for both the XML and HTML parser (though the HTML parser`
			`need more state).</li>`
			`<li>If you are generating the DOM tree then memory requirements will grow`
			`nearly linear with the size of the data. In general for a balanced`
			`textual document the internal memory requirement is about 4 times the`
			`size of the UTF8 serialization of this document (example the XML-1.0`
			`recommendation is a bit more of 150KBytes and takes 650KBytes of main`
			`memory when parsed). Validation will add a amount of memory required for`
			`maintaining the external Dtd state which should be linear with the`
			`complexity of the content model defined by the Dtd</li>`
			`<li>If you need to work with fixed memory requirements or don't need the`
			`full DOM tree then using the <a href="xmlreader.html">xmlReader`
			`interface</a> is probably the best way to proceed, it still allows to`
			`validate or operate on subset of the tree if needed.</li>`
			`<li>If you don't care about the advanced features of libxml2 like`
			`validation, DOM, XPath or XPointer, don't use entities, need to work with`
			`fixed memory requirements, and try to get the fastest parsing possible`
			`then the SAX interface should be used, but it has known restrictions.</li>`
added a small section on returning memory to the kernel by compacting the * doc/xml.html doc/xmlmem.html: added a small section on returning memory to the kernel by compacting the heap provided by Wolfram Sang Daniel svn path=/trunk/; revision=3682 2008-02-04 16:50:03 +00:00			`</ul><p></p><h3><a name="Compacting" id="Compacting">Returning memory to the kernel</a></h3><p>You may encounter that your process using libxml2 does not have a`
			`reduced memory usage although you freed the trees. This is because`
			`libxml2 allocates memory in a number of small chunks. When freeing one`
			`of those chunks, the OS may decide that giving this little memory back`
			`to the kernel will cause too much overhead and delay the operation. As`
			`all chunks are this small, they get actually freed but not returned to`
			`the kernel. On systems using glibc, there is a function call`
			`"malloc_trim" from malloc.h which does this missing operation (note that`
			`it is allowed to fail). Thus, after freeing your tree you may simply try`
			`"malloc_trim(0);" to really get the memory back. If your OS does not`
			`provide malloc_trim, try searching for a similar function.</p><p></p><p><a href="bugs.html">Daniel Veillard</a></p></td></tr></table></td></tr></table></td></tr></table></td></tr></table></td></tr></table></body></html>`