Memory-leaks.html 14 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278
  1. <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
  2. <html>
  3. <!-- Created on December 10, 2012 by texi2html 1.82
  4. texi2html was written by:
  5. Lionel Cons <[email protected]> (original author)
  6. Karl Berry <[email protected]>
  7. Olaf Bachmann <[email protected]>
  8. and many others.
  9. Maintained by: Many creative people.
  10. Send bugs and suggestions to <[email protected]>
  11. -->
  12. <head>
  13. <title>avram - a virtual machine code interpreter: 3.9.3.2 Memory leaks</title>
  14. <meta name="description" content="avram - a virtual machine code interpreter: 3.9.3.2 Memory leaks">
  15. <meta name="keywords" content="avram - a virtual machine code interpreter: 3.9.3.2 Memory leaks">
  16. <meta name="resource-type" content="document">
  17. <meta name="distribution" content="global">
  18. <meta name="Generator" content="texi2html 1.82">
  19. <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
  20. <style type="text/css">
  21. <!--
  22. a.summary-letter {text-decoration: none}
  23. blockquote.smallquotation {font-size: smaller}
  24. pre.display {font-family: serif}
  25. pre.format {font-family: serif}
  26. pre.menu-comment {font-family: serif}
  27. pre.menu-preformatted {font-family: serif}
  28. pre.smalldisplay {font-family: serif; font-size: smaller}
  29. pre.smallexample {font-size: smaller}
  30. pre.smallformat {font-family: serif; font-size: smaller}
  31. pre.smalllisp {font-size: smaller}
  32. span.roman {font-family:serif; font-weight:normal;}
  33. span.sansserif {font-family:sans-serif; font-weight:normal;}
  34. ul.toc {list-style: none}
  35. -->
  36. </style>
  37. </head>
  38. <body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
  39. <a name="Memory-leaks"></a>
  40. <table cellpadding="1" cellspacing="1" border="0">
  41. <tr><td valign="middle" align="left">[<a href="Inept-excess-verbiage.html#Inept-excess-verbiage" title="Previous section in reading order"> &lt; </a>]</td>
  42. <td valign="middle" align="left">[<a href="Suicidal-exception-handling.html#Suicidal-exception-handling" title="Next section in reading order"> &gt; </a>]</td>
  43. <td valign="middle" align="left"> &nbsp; </td>
  44. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  45. <td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Up section"> Up </a>]</td>
  46. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  47. <td valign="middle" align="left"> &nbsp; </td>
  48. <td valign="middle" align="left"> &nbsp; </td>
  49. <td valign="middle" align="left"> &nbsp; </td>
  50. <td valign="middle" align="left"> &nbsp; </td>
  51. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  52. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  53. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  54. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  55. </tr></table>
  56. <hr size="1">
  57. <a name="Memory-leaks-1"></a>
  58. <h4 class="subsubsection">3.9.3.2 Memory leaks</h4>
  59. <p>Incorrect memory management may undermine confidence in a library when
  60. one wonders what else it gets wrong, but if the worst it does is leave
  61. a few bytes unreclaimed, then help is at hand.
  62. </p>
  63. <p>The first priority is to assess the seriousness of the situation.
  64. Similarly to the way library functions are bracketed with calls to
  65. those listed in <a href="Inept-excess-verbiage.html#Inept-excess-verbiage">Inept excess verbiage</a>, the following functions
  66. are meant to be placed before and after a call to a library function
  67. either for diagnostic purposes or production use.
  68. </p>
  69. <dl>
  70. <dt><a name="index-avm_005fmanage_005fmemory"></a><u>Function:</u> void <b>avm_manage_memory</b><i> ()</i></dt>
  71. <dd><p>After this function is called, all subsequent calls to the standard C
  72. functions <code>malloc</code>, <code>free</code>, and <code>realloc</code> are
  73. intercepted and logged until the next time
  74. <code>avm_dont_manage_memory</code> is called. Furthermore, a complete
  75. record is maintained of the addresses and sizes of all allocated areas
  76. of memory during this time in a persistent data structure managed
  77. internally.
  78. </p></dd></dl>
  79. <dl>
  80. <dt><a name="index-avm_005fdont_005fmanage_005fmemory"></a><u>Function:</u> void <b>avm_dont_manage_memory</b><i> ()</i></dt>
  81. <dd><p>Calling this function suspends the storage monitoring activities
  82. initiated by calling <code>avm_manage_memory</code>, but the record of
  83. allocated memory areas is not erased.
  84. </p></dd></dl>
  85. <dl>
  86. <dt><a name="index-avm_005fdebug_005fmemory"></a><u>Function:</u> void <b>avm_debug_memory</b><i> ()</i></dt>
  87. <dd><p>After this function is called and <code>avm_manage_memory</code> is also
  88. called, the standard output stream will display a running account of
  89. the sizes and addresses of all memory allocations or deallocations as
  90. they occur until the next call to either <code>avm_dont_debug_memory</code>
  91. or <code>avm_dont_manage_memory</code>.
  92. </p></dd></dl>
  93. <dl>
  94. <dt><a name="index-avm_005fdont_005fdebug_005fmemory"></a><u>Function:</u> void <b>avm_dont_debug_memory</b><i> ()</i></dt>
  95. <dd><p>This function stops the output being sent to <code>stdout</code> caused by
  96. <code>avm_debug_memory</code>, if any, but has no effect on the logging of
  97. memory management events preformed due to <code>avm_manage_memory</code>.
  98. </p></dd></dl>
  99. <p>While the latter two are not useful in production code, they can help
  100. to clarify an inadequately documented API during development by
  101. experimentally identifying the functions that cause memory to be
  102. allocated. They can also provide the answer to questions like whether
  103. separate copies are made from arrays passed to functions (useful for
  104. knowing when it&rsquo;s appropriate to free them).
  105. </p>
  106. <p>Although the console output reveals everything there is to know about
  107. memory management during the selected window, the question of
  108. unreclaimed storage is more directly settled by the following
  109. functions.
  110. </p>
  111. <dl>
  112. <dt><a name="index-avm_005finitialize_005fmwrap"></a><u>Function:</u> void <b>avm_initialize_mwrap</b><i> ()</i></dt>
  113. <dd><p>This function has to be called before any other functions from
  114. &lsquo;<tt>mwrap.h</tt>&rsquo; in order to clean the slate and prepare the static data
  115. structures for use. This function might not have to be called
  116. explicitly if the client module is part of <code>avram</code>, whose main
  117. program would have already called it. There is no harm in calling it
  118. repeatedly.
  119. </p></dd></dl>
  120. <dl>
  121. <dt><a name="index-avm_005fcount_005fmwrap"></a><u>Function:</u> void <b>avm_count_mwrap</b><i> ()</i></dt>
  122. <dd><p>This function should be called after the last call to any other
  123. functions in &lsquo;<tt>mwrap.h</tt>&rsquo;, when it is expected that all storage that
  124. was allocated while <code>avm_manage_memory</code> was in effect should have
  125. been reclaimed.
  126. </p>
  127. <p>If there is no unreclaimed storage allocated during an interval when
  128. memory was being managed, this function returns uneventfully. However,
  129. if any storage remains unreclaimed, a message stating the number of
  130. bytes is written to <code>stderr</code>.
  131. </p>
  132. <p>If <code>avm_debug_memory</code> is also in effect when this function
  133. detects unreclaimed storage, an itemized list of the unreclaimed
  134. memory addresses and their sizes is written to standard output.
  135. </p></dd></dl>
  136. <p>Of course, in order for <code>avm_count_mwrap</code> to report meaningful
  137. results, any memory that is allocated during the interval between
  138. calls to <code>avm_manage_memory</code> and <code>avm_dont_manage_memory</code>
  139. must have been given an opportunity to be reclaimed also while
  140. this logging mechanism is in effect. However, there may be arbitrarily
  141. many intervening intervals during which it is suspended.
  142. </p>
  143. <p>On the other hand, any storage that is allocated when memory is not
  144. being managed must not be freed at a time when it is (except for
  145. freeing a <code>NULL</code> pointer, which is tolerated but not
  146. encouraged). Doing so raises an internal error, causing termination
  147. <a name="index-internal-error"></a>
  148. with extreme prejudice. This behavior is a precaution against library
  149. functions freeing storage that they didn&rsquo;t allocate, which would mean
  150. no memory is safe and it&rsquo;s better for <code>avram</code> not to continue.
  151. </p>
  152. <p>If these investigations uncover no evidence of a memory leak, then
  153. perhaps the relevant library functions are reliable enough to run
  154. without supervisory memory management. Alternatively, when memory
  155. leaks are indicated, the next function provides a simple remedy.
  156. </p>
  157. <dl>
  158. <dt><a name="index-avm_005ffree_005fmanaged_005fmemory"></a><u>Function:</u> void <b>avm_free_managed_memory</b><i> ()</i></dt>
  159. <dd><p>This function causes all storage to be reclaimed that was allocated
  160. at any time while logging of memory allocation was in effect (i.e.,
  161. whenever <code>avm_manage_memory</code> had been called more recently than
  162. <code>avm_dont_manage_memory</code>). When the storage is freed, no further
  163. record of it is maintained.
  164. </p>
  165. <p>A side effect of this function is to call <code>avm_dont_manage_memory</code>
  166. and therefore leave memory management turned off.
  167. </p></dd></dl>
  168. <p>This last function when used in conjunction with the others is
  169. therefore the workaround for library functions that don&rsquo;t clean up
  170. after themselves. It may be important to do it for them if repeated
  171. calls to the library function are expected, which would otherwise
  172. cause unreclaimed storage to accumulate until it curtailed other
  173. operations.
  174. </p>
  175. <p>One small issue with this function is the assumption that unreclaimed
  176. storage is really a leak and not internal library data that is
  177. designed to persist between calls. If this assumption is not valid,
  178. breakage will occur. However, libraries deliberately making use of
  179. persistent data are likely to have initialization and destructor
  180. functions as part of their API&rsquo;s, so this assumption is often
  181. justified if they don&rsquo;t.
  182. </p>
  183. <p>An example of using these functions is given below.
  184. </p>
  185. <p>In this example, <code>allocated_library_object</code> is a hypothetical
  186. function exported by an external library that causes storage to be
  187. allocated, and <code>library_reclamation_routine</code> is provided by the
  188. same library ostensibly to reclaim the storage thus
  189. allocated. However, the latter is suspected of memory leaks.
  190. </p>
  191. <p>The variable <code>my_data</code> is declared and used by an <code>avram</code>
  192. developer who is presumably competent to reclaim it correctly, rather
  193. than it being part of an external library. Memory management is
  194. therefore enabled during the calls to the library routines but not at
  195. other times.
  196. </p>
  197. <p>The call to <code>avm_count_mwrap</code> is redundant immediately after a
  198. call to <code>avm_free_managed_memory</code>, because with all managed
  199. memory having been freed, no memory leak will ever be detected, but it
  200. is included for illustrative purposes.
  201. </p>
  202. <table><tr><td>&nbsp;</td><td><pre class="example">#include &lt;avm/mwrap.h&gt;
  203. ...
  204. {
  205. void *behemoth;
  206. char *my_data;
  207. avm_initialize_mwrap ();
  208. avm_manage_memory ();
  209. behemoth = allocated_library_object (foo, bar);
  210. avm_dont_manage_memory ();
  211. my_data = (char *) malloc (100);
  212. ...
  213. free (my_data);
  214. avm_manage_memory ();
  215. library_reclamation_routine (&amp;behemoth);
  216. avm_free_managed_memory ();
  217. avm_count_mwrap ();
  218. return;
  219. }
  220. </pre></td></tr></table>
  221. <p>It might be a cleaner solution in some sense to omit the call to
  222. <code>library_reclamation_routine</code> entirely, because the storage
  223. allocated during the call to <code>allocated_library_object</code> will be
  224. reclaimed perfectly well by <code>avm_free_managed_memory</code> without
  225. it. Doing so may also be the only option if the library reclamation
  226. routine is either extremely unreliable or non-existent. However, the
  227. style above is to be preferred for portability if possible. The memory
  228. management functions rely on the availability of the system header
  229. file <code>malloc.h</code>, and GNU C library features whose portability is
  230. not assured. If the required features are not detected on the host
  231. system at configuration time, conditional directives in the
  232. <code>avram</code> source will make the <code>avm_</code>* memory management
  233. functions perform no operations, and the responsibility for memory
  234. management will devolve to the possibly less robust external library
  235. implementation.
  236. </p>
  237. <hr size="1">
  238. <table cellpadding="1" cellspacing="1" border="0">
  239. <tr><td valign="middle" align="left">[<a href="Inept-excess-verbiage.html#Inept-excess-verbiage" title="Previous section in reading order"> &lt; </a>]</td>
  240. <td valign="middle" align="left">[<a href="Suicidal-exception-handling.html#Suicidal-exception-handling" title="Next section in reading order"> &gt; </a>]</td>
  241. <td valign="middle" align="left"> &nbsp; </td>
  242. <td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
  243. <td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Up section"> Up </a>]</td>
  244. <td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
  245. <td valign="middle" align="left"> &nbsp; </td>
  246. <td valign="middle" align="left"> &nbsp; </td>
  247. <td valign="middle" align="left"> &nbsp; </td>
  248. <td valign="middle" align="left"> &nbsp; </td>
  249. <td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
  250. <td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
  251. <td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
  252. <td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
  253. </tr></table>
  254. <p>
  255. <font size="-1">
  256. This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
  257. </font>
  258. <br>
  259. </p>
  260. </body>
  261. </html>