Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / libxml2 / c5d64345cf19bfd72418eb0a837869b0462e9130 / . / doc / xmlmem.html
blob: e16e69ac63829de37387acfdc870784569a853c7 [file] [log] [blame]
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
2 "http://www.w3.org/TR/REC-html40/loose.dtd">
3<html>
4<head>
5 <title>Libxml memory management</title>
6 <meta name="GENERATOR" content="amaya V3.2">
7 <meta http-equiv="Content-Type" content="text/html">
8</head>
9
10<body bgcolor="#ffffff">
11<h1 align="center">Libxml memory management</h1>
12
13<p>Location: <a
14href="http://xmlsoft.org/xmlmem.html">http://xmlsoft.org/xmlmem.html</a></p>
15
16<p>Libxml home page: <a href="http://xmlsoft.org/">http://xmlsoft.org/</a></p>
17
18<p>Mailing-list archive: <a
19href="http://xmlsoft.org/messages/">http://xmlsoft.org/messages/</a></p>
20
21<p>Version: $Revision$</p>
22
23<p>Table of Content:</p>
24<ol>
25 <li><a href="#General">General overview</a></li>
26 <li><a href="#setting">Setting libxml set of memory routines</a></li>
27 <li><a href="#cleanup">Cleaning up after parsing</a></li>
28 <li><a href="#Debugging">Debugging routines</a></li>
29 <li><a href="#General">General memory requirements</a></li>
30</ol>
31
32<h2><a name="General">General overview</a></h2>
33
34<p>The module <code><a
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]35href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlmemory.h</a></code>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]36provides the interfaces to the libxml memory system:</p>
37<ul>
38 <li>libxml does not use the libc memory allocator directly but xmlFree(),
39 xmlMalloc() and xmlRealloc()</li>
40 <li>those routines can be reallocated to a specific set of routine, by
41 default the libc ones i.e. free(), malloc() and realloc()</li>
42 <li>the xmlmemory.c module includes a set of debugging routine</li>
43</ul>
44
45<h2><a name="setting">Setting libxml set of memory routines</a></h2>
46
47<p>It is sometimes useful to not use the default memory allocator, either for
48debugging, analysis or to implement a specific behaviour on memory management
49(like on embedded systems). Two function calls are available to do so:</p>
50<ul>
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]51 <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemGet
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]52 ()</a> which return the current set of functions in use by the parser</li>
53 <li><a
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]54 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemSetup()</a>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]55 which allow to set up a new set of memory allocation functions</li>
56</ul>
57
58<p>Of course a call to xmlMemSetup() should probably be done before calling
59any other libxml routines (unless you are sure your allocations routines are
60compatibles).</p>
61
62<h2><a name="cleanup">Cleaning up after parsing</a></h2>
63
64<p>Libxml is not stateless, there is a few set of memory structures needing
65allocation before the parser is fully functionnal (some encoding structures
66for example). This also mean that once parsing is finished there is a tiny
67amount of memory (a few hundred bytes) which can be recollected if you don't
68reuse the parser immediately:</p>
69<ul>
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]70 <li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlCleanupParser
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]71 ()</a> is a centralized routine to free the parsing states. Note that it
72 won't deallocate any produced tree if any (use the xmlFreeDoc() and
73 related routines for this).</li>
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]74 <li><a href="http://xmlsoft.org/html/libxml-parser.html">xmlInitParser
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]75 ()</a> is the dual routine allowing to preallocate the parsing state which
76 can be useful for example to avoid initialization reentrancy problems when
77 using libxml in multithreaded applications</li>
78</ul>
79
80<p>Generally xmlCleanupParser() is safe, if needed the state will be rebuild
81at the next invocation of parser routines, but be careful of the consequences
82in multithreaded applications.</p>
83
84<h2><a name="Debugging">Debugging routines</a></h2>
85
86<p>When configured using --with-mem-debug flag (off by default), libxml uses a
87set of memory allocation debugging routineskeeping track of all allocated
88blocks and the location in the code where the routine was called. A couple of
89other debugging routines allow to dump the memory allocated infos to a file or
90call a specific routine when a given block number is allocated:</p>
91<ul>
92 <li><a
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]93 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMallocLoc()</a>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]94 <a
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]95 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlReallocLoc()</a>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]96 and <a
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]97 href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemStrdupLoc()</a>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]98 are the memory debugging replacement allocation routines</li>
Daniel Veillard9cb5ff42001-01-29 08:22:21 +0000[diff] [blame]99 <li><a href="http://xmlsoft.org/html/libxml-xmlmemory.html">xmlMemoryDump
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]100 ()</a> dumps all the informations about the allocated memory block lefts
101 in the <code>.memdump</code> file</li>
102</ul>
103
104<p> When developping libxml memory debug is enabled, the tests programs call
105xmlMemoryDump () and the "make test" regression tests will check for any
106memory leak during the full regression test sequence, this helps a lot
107ensuring that libxml does not leak memory and bullet proof memory allocations
108use (some libc implementations are known to be far too permissive resulting in
109major portability problems!). </p>
110
111<p>If the .memdump reports a leak, it displays the allocation function and
112also tries to give some informations about the content and structure of the
113allocated blocks left. This is sufficient in most cases to find the culprit,
114but not always. Assuming the allocation problem is reproductible, it is
115possible to find more easilly:</p>
116<ol>
117 <li>write down the block number xxxx not allocated</li>
118 <li>export the environement variable XML_MEM_BREAKPOINT=xxxx</li>
119 <li>run the program under a debugger and set a breakpoint on
120 xmlMallocBreakpoint() a specific function called when this precise block
121 is allocated</li>
122 <li>when the breakpoint is reached you can then do a fine analysis of the
123 allocation an step to see the condition resulting in the missing
124 deallocation.</li>
125</ol>
126
127<p> I used to use a commercial tool to debug libxml memory problems but after
128noticing that it was not detecting memory leaks that simple mechanism was used
129and proved extremely efficient until now.</p>
130
131<h2><a name="General">General memory requirements</a></h2>
132
133<p>How much libxml memory require ? It's hard to tell in average it depends of
134a number of things:</p>
135<ul>
136 <li>the parser itself should work in a fixed amout of memory, except for
137 information maintained about the stacks of names and entities locations.
138 The I/O and encoding handlers will probably account for a few KBytes. This
139 is true for both the XML and HTML parser (though the HTML parser need more
140 state).</li>
141 <li>If you are generating the DOM tree then memory requirements will grow
142 nearly lineary with the size of the data. In general for a balanced
143 textual document the internal memory requirement is about 4 times the size
144 of the UTF8 serialization of this document (exmple the XML-1.0
145 recommendation is a bit more of 150KBytes and takes 650KBytes of main
146 memory when parsed). Validation will add a amount of memory required for
147 maintaining the external Dtd state which should be linear with the
148 complexity of the content model defined by the Dtd </li>
149 <li>If you don't care about the advanced features of libxml like validation,
150 DOM, XPath or XPointer, but really need to work fixed memory requirements,
151 then the SAX interface should be used.</li>
152</ul>
153
154<p></p>
155
Daniel Veillardc5d64342001-06-24 12:13:24 +0000[diff] [blame^]156<p><a href="mailto:daniel@veillard.com">Daniel Veillard</a></p>
Daniel Veillard189446d2000-10-13 10:23:06 +0000[diff] [blame]157
158<p>$Id$</p>
159</body>
160</html>