txlyre
/
avram


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278
							<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created on December 10, 2012 by texi2html 1.82
texi2html was written by: 
            Lionel Cons <[email protected]> (original author)
            Karl Berry  <[email protected]>
            Olaf Bachmann <[email protected]>
            and many others.
Maintained by: Many creative people.
Send bugs and suggestions to <[email protected]>
-->
<head>
<title>avram - a virtual machine code interpreter: 3.9.3.2 Memory leaks</title>

<meta name="description" content="avram - a virtual machine code interpreter: 3.9.3.2 Memory leaks">
<meta name="keywords" content="avram - a virtual machine code interpreter: 3.9.3.2 Memory leaks">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.82">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.roman {font-family:serif; font-weight:normal;}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>


</head>

<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">

<a name="Memory-leaks"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Inept-excess-verbiage.html#Inept-excess-verbiage" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Suicidal-exception-handling.html#Suicidal-exception-handling" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<hr size="1">
<a name="Memory-leaks-1"></a>
<h4 class="subsubsection">3.9.3.2 Memory leaks</h4>

<p>Incorrect memory management may undermine confidence in a library when
one wonders what else it gets wrong, but if the worst it does is leave
a few bytes unreclaimed, then help is at hand.
</p>
<p>The first priority is to assess the seriousness of the situation.
Similarly to the way library functions are bracketed with calls to
those listed in <a href="Inept-excess-verbiage.html#Inept-excess-verbiage">Inept excess verbiage</a>, the following functions
are meant to be placed before and after a call to a library function
either for diagnostic purposes or production use.
</p>
<dl>
<dt><a name="index-avm_005fmanage_005fmemory"></a><u>Function:</u> void <b>avm_manage_memory</b><i> ()</i></dt>
<dd><p>After this function is called, all subsequent calls to the standard C
functions <code>malloc</code>, <code>free</code>, and <code>realloc</code> are
intercepted and logged until the next time
<code>avm_dont_manage_memory</code> is called. Furthermore, a complete
record is maintained of the addresses and sizes of all allocated areas
of memory during this time in a persistent data structure managed
internally.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005fdont_005fmanage_005fmemory"></a><u>Function:</u> void <b>avm_dont_manage_memory</b><i> ()</i></dt>
<dd><p>Calling this function suspends the storage monitoring activities
initiated by calling <code>avm_manage_memory</code>, but the record of
allocated memory areas is not erased.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005fdebug_005fmemory"></a><u>Function:</u> void <b>avm_debug_memory</b><i> ()</i></dt>
<dd><p>After this function is called and <code>avm_manage_memory</code> is also
called, the standard output stream will display a running account of
the sizes and addresses of all memory allocations or deallocations as
they occur until the next call to either <code>avm_dont_debug_memory</code>
or <code>avm_dont_manage_memory</code>.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005fdont_005fdebug_005fmemory"></a><u>Function:</u> void <b>avm_dont_debug_memory</b><i> ()</i></dt>
<dd><p>This function stops the output being sent to <code>stdout</code> caused by
<code>avm_debug_memory</code>, if any, but has no effect on the logging of
memory management events preformed due to <code>avm_manage_memory</code>.
</p></dd></dl>

<p>While the latter two are not useful in production code, they can help
to clarify an inadequately documented API during development by
experimentally identifying the functions that cause memory to be
allocated. They can also provide the answer to questions like whether
separate copies are made from arrays passed to functions (useful for
knowing when it&rsquo;s appropriate to free them).
</p>
<p>Although the console output reveals everything there is to know about
memory management during the selected window, the question of
unreclaimed storage is more directly settled by the following
functions.
</p>
<dl>
<dt><a name="index-avm_005finitialize_005fmwrap"></a><u>Function:</u> void <b>avm_initialize_mwrap</b><i> ()</i></dt>
<dd><p>This function has to be called before any other functions from
&lsquo;<tt>mwrap.h</tt>&rsquo; in order to clean the slate and prepare the static data
structures for use. This function might not have to be called
explicitly if the client module is part of <code>avram</code>, whose main
program would have already called it. There is no harm in calling it
repeatedly.
</p></dd></dl>

<dl>
<dt><a name="index-avm_005fcount_005fmwrap"></a><u>Function:</u> void <b>avm_count_mwrap</b><i> ()</i></dt>
<dd><p>This function should be called after the last call to any other
functions in &lsquo;<tt>mwrap.h</tt>&rsquo;, when it is expected that all storage that
was allocated while <code>avm_manage_memory</code> was in effect should have
been reclaimed.
</p>
<p>If there is no unreclaimed storage allocated during an interval when
memory was being managed, this function returns uneventfully. However,
if any storage remains unreclaimed, a message stating the number of
bytes is written to <code>stderr</code>.
</p>
<p>If <code>avm_debug_memory</code> is also in effect when this function
detects unreclaimed storage, an itemized list of the unreclaimed
memory addresses and their sizes is written to standard output.
</p></dd></dl>

<p>Of course, in order for <code>avm_count_mwrap</code> to report meaningful
results, any memory that is allocated during the interval between
calls to <code>avm_manage_memory</code> and <code>avm_dont_manage_memory</code>
must have been given an opportunity to be reclaimed also while
this logging mechanism is in effect. However, there may be arbitrarily
many intervening intervals during which it is suspended.
</p>
<p>On the other hand, any storage that is allocated when memory is not
being managed must not be freed at a time when it is (except for
freeing a <code>NULL</code> pointer, which is tolerated but not
encouraged). Doing so raises an internal error, causing termination
<a name="index-internal-error"></a>
with extreme prejudice. This behavior is a precaution against library
functions freeing storage that they didn&rsquo;t allocate, which would mean
no memory is safe and it&rsquo;s better for <code>avram</code> not to continue.
</p>
<p>If these investigations uncover no evidence of a memory leak, then
perhaps the relevant library functions are reliable enough to run
without supervisory memory management. Alternatively, when memory
leaks are indicated, the next function provides a simple remedy.
</p>
<dl>
<dt><a name="index-avm_005ffree_005fmanaged_005fmemory"></a><u>Function:</u> void <b>avm_free_managed_memory</b><i> ()</i></dt>
<dd><p>This function causes all storage to be reclaimed that was allocated
at any time while logging of memory allocation was in effect (i.e.,
whenever <code>avm_manage_memory</code> had been called more recently than
<code>avm_dont_manage_memory</code>). When the storage is freed, no further
record of it is maintained.
</p>
<p>A side effect of this function is to call <code>avm_dont_manage_memory</code>
and therefore leave memory management turned off.
</p></dd></dl>

<p>This last function when used in conjunction with the others is
therefore the workaround for library functions that don&rsquo;t clean up
after themselves. It may be important to do it for them if repeated
calls to the library function are expected, which would otherwise
cause unreclaimed storage to accumulate until it curtailed other
operations.
</p>
<p>One small issue with this function is the assumption that unreclaimed
storage is really a leak and not internal library data that is
designed to persist between calls. If this assumption is not valid,
breakage will occur. However, libraries deliberately making use of
persistent data are likely to have initialization and destructor
functions as part of their API&rsquo;s, so this assumption is often
justified if they don&rsquo;t.
</p>
<p>An example of using these functions is given below.
</p>
<p>In this example, <code>allocated_library_object</code> is a hypothetical
function exported by an external library that causes storage to be
allocated, and <code>library_reclamation_routine</code> is provided by the
same library ostensibly to reclaim the storage thus
allocated. However, the latter is suspected of memory leaks.
</p>
<p>The variable <code>my_data</code> is declared and used by an <code>avram</code>
developer who is presumably competent to reclaim it correctly, rather
than it being part of an external library. Memory management is
therefore enabled during the calls to the library routines but not at
other times.
</p>
<p>The call to <code>avm_count_mwrap</code> is redundant immediately after a
call to <code>avm_free_managed_memory</code>, because with all managed
memory having been freed, no memory leak will ever be detected, but it
is included for illustrative purposes.
</p>
<table><tr><td>&nbsp;</td><td><pre class="example">#include &lt;avm/mwrap.h&gt;
...

{
  void *behemoth;
  char *my_data;

  avm_initialize_mwrap ();
  avm_manage_memory ();
  behemoth = allocated_library_object (foo, bar);
  avm_dont_manage_memory ();
  my_data = (char *) malloc (100);
  ...
  free (my_data);
  avm_manage_memory ();
  library_reclamation_routine (&amp;behemoth);
  avm_free_managed_memory ();
  avm_count_mwrap ();
  return;
}
</pre></td></tr></table>

<p>It might be a cleaner solution in some sense to omit the call to
<code>library_reclamation_routine</code> entirely, because the storage
allocated during the call to <code>allocated_library_object</code> will be
reclaimed perfectly well by <code>avm_free_managed_memory</code> without
it. Doing so may also be the only option if the library reclamation
routine is either extremely unreliable or non-existent. However, the
style above is to be preferred for portability if possible. The memory
management functions rely on the availability of the system header
file <code>malloc.h</code>, and GNU C library features whose portability is
not assured.  If the required features are not detected on the host
system at configuration time, conditional directives in the
<code>avram</code> source will make the <code>avm_</code>* memory management
functions perform no operations, and the responsibility for memory
management will devolve to the possibly less robust external library
implementation.
</p>
<hr size="1">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Inept-excess-verbiage.html#Inept-excess-verbiage" title="Previous section in reading order"> &lt; </a>]</td>
<td valign="middle" align="left">[<a href="Suicidal-exception-handling.html#Suicidal-exception-handling" title="Next section in reading order"> &gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="Library-Reference.html#Library-Reference" title="Beginning of this chapter or previous chapter"> &lt;&lt; </a>]</td>
<td valign="middle" align="left">[<a href="Working-around-library-misfeatures.html#Working-around-library-misfeatures" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Character-Table.html#Character-Table" title="Next chapter"> &gt;&gt; </a>]</td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left"> &nbsp; </td>
<td valign="middle" align="left">[<a href="avram.html#Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="avram_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="Function-Index.html#Function-Index" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="avram_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
 <font size="-1">
  This document was generated on <i>December 10, 2012</i> using <a href="http://www.nongnu.org/texi2html/"><i>texi2html 1.82</i></a>.
 </font>
 <br>

</p>
</body>
</html>