<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<title>Basic memory management</title>
</head>
<body><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="internals2.memory.html">Memory management</a></div>
<div class="next" style="text-align: right; float: right;"><a href="internals2.memory.persistence.html">Data persistence</a></div>
<div class="up"><a href="internals2.memory.html">Memory management</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div><hr /><div id="internals2.memory.management" class="sect1">
<h2 class="title">Basic memory management</h2>
<p class="para">
The engine's memory management is implemented with features important to a system like PHP. The exact functionality of the engine's memory management and the optmizations performed are out of the scope of this document. However, a good understanding of its functionality provides a basis for a good understanding of the rest of the <code class="code">Hacker's Guide</code>, and introduce you to terminology and functionality used throughout PHP.
</p>
<p class="para">
The most important of its features for the <code class="code">Hacker</code>, and the first thing to mention is tracking allocations. Tracking allocations allow the memory manager to avoid leaks, a thorn in the side of most <code class="code">Hackers</code>. When PHP is built in debug mode (<code class="code">--enable-debug</code>), detected leaks are reported, in a perfect world they would never get to deployment.
</p>
<p class="para">While tracking allocations is an important, and highly useful feature, the <code class="code">Hacker</code> should not become lazy! Always attempt to resolve leaks before deploying your code, a memory leak in a SAPI environment can become a very big problem, very quickly.</p>
<p class="para">Another, perhaps more incidental but still noteworthy, feature is that the memory manager is the part that allows a hard limit on memory usage for each instance of PHP. As we all know, there is no such thing as unlimited. If some code is running out of memory, it is likely to be written wrong, either by the <code class="code">Hacker</code>, or the programmer of PHP. Limiting the memory therefore is not a restriction on the language that is supposed to be experienced in production, it is simply a way from stopping development environments from spiraling out of control when mistakes are made, and equally, when bugs are found in production.</p>
<p class="para">From the <code class="code">Hacker's</code> perspective, the memory management API looks very much like libc's (or whoever the <code class="code">Hacker</code> prefers !) malloc implementation.</p>
<table id="internals2.memory.management.apis" class="doctable table">
<caption><strong>Main memory APIs</strong></caption>
<thead>
<tr>
<th>Prototype</th>
<th>Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr>
<td><code class="code">void *emalloc(size_t size)</code></td>
<td>Allocate <code class="code">size</code> bytes of memory.</td>
</tr>
<tr>
<td><code class="code">void *ecalloc(size_t nmemb, size_t size)</code></td>
<td>
Allocate a buffer for <code class="code">nmemb</code> elements of
<code class="code">size</code> bytes and makes sure it is initialized with zeros.
</td>
</tr>
<tr>
<td><code class="code">void *erealloc(void *ptr, size_t size)</code></td>
<td>
Resize the buffer <code class="code">ptr</code>, which was allocated using
<code class="code">emalloc</code> to hold <code class="code">size</code> bytes of memory.
</td>
</tr>
<tr>
<td><code class="code">void efree(void *ptr)</code></td>
<td>
Free the buffer pointed by <code class="code">ptr</code>. The buffer had to be
allocated by <code class="code">emalloc</code>.
</td>
</tr>
<tr>
<td>
<code class="code">void *safe_emalloc(size_t nmemb, size_t size, size_t offset)</code>
</td>
<td>
Allocate a buffer for holding <code class="code">nmemb</code> blocks of each
<code class="code">size</code> bytes and an additional <code class="code">offset</code> bytes.
This is similar to <code class="code">emalloc(nmemb * size + offset)</code> but adds
a special protection against overflows.
</td>
</tr>
<tr>
<td><code class="code">char *estrdup(const char *s)</code></td>
<td>
Allocate a buffer that can hold the NULL-terminated string
<code class="code">s</code> and copy the <code class="code">s</code> into that buffer.
</td>
</tr>
<tr>
<td>
<code class="code">char *estrndup(const char *s, unsigned int length)</code>
</td>
<td>
Similar to <code class="code">estrdup</code> while the length of the
NULL-terminated string is already known.
</td>
</tr>
</tbody>
</table>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">
The engines memory management functions do not return <code class="code">NULL</code> upon failure, if memory cannot be allocated at runtime, the engine bails and raises an error.
</span>
</p></blockquote>
<div class="caution"><strong class="caution">Caution</strong>
<p class="simpara">
Always use valgrind before deploying code and as a normal part of the <code class="code">Hacker's</code> process. The engine can only report and detect leaks where it has allocated the memory. All of PHP is only a thin wrapper around third parties, those third parties do not use the engines memory management. Additionally, valgrind will catch errors that do not always halt or even have an apparent effect at execution time, it is just as important that there should be no errors, as it is important that avoidable leaks should be avoided.
</p>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">Some leaks are unavoidable, some libraries rely on the end of a process to free some of their structures, this is normal under some circumstances and acceptable where it is out of the <code class="code">Hacker's</code> control.</span>
</p></blockquote>
<p class="simpara">While executing in a debug environment, configured with <code class="code">--enable-debug</code>, the leak function used in the next example is actually implemented by the engine and is available to call in userland.</p>
<div class="example" id="internals2.memory.management.example.leak">
<p><strong>Example #1 Leak Detection in Action</strong></p>
<div class="example-contents">
<div class="ccode"><pre class="ccode">ZEND_FUNCTION(leak)
{
long leakbytes = 3;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|l", &leakbytes) == FAILURE) {
return;
}
emalloc(leakbytes);
}</pre>
</div>
</div>
<div class="example-contents"><p>The above example will output
something similar to:</p></div>
<div class="example-contents screen">
<div class="cdata"><pre>
[Thu Oct 22 02:14:57 2009] Script: '-'
/home/johannes/src/PHP_5_3/Zend/zend_builtin_functions.c(1377) : Freeing 0x088888D4 (3 bytes), script=-
=== Total 1 memory leaks detected ===
</pre></div>
</div>
</div>
<blockquote class="note"><p><strong class="note">Note</strong>:
<span class="simpara">USE_ZEND_ALLOC=0 in the environment will stop the memory manager from functioning, all allocations fall back on the default system allocators which can be useful for debugging leaks.</span>
</p></blockquote>
</div><hr /><div class="manualnavbar" style="text-align: center;">
<div class="prev" style="text-align: left; float: left;"><a href="internals2.memory.html">Memory management</a></div>
<div class="next" style="text-align: right; float: right;"><a href="internals2.memory.persistence.html">Data persistence</a></div>
<div class="up"><a href="internals2.memory.html">Memory management</a></div>
<div class="home"><a href="index.html">PHP Manual</a></div>
</div></body></html>
