When programming in the C programming language the developer has to manually care about memory management. As PHP is usually used as a web server module memory management is from special relevance in order to prevent memory leaks. Additionally you should be aware that PHP might be used in threaded environments which means that global variables might lead to race conditions. For information about dealing with thread-global data please refer to the documentation on the Thread-Safe Resource Manager, which serves as thread-isolation facility.
Additionally to these requirements the Zend Engine is faced with a quite special usage pattern where, within a relatively short time, many memory blocks of the size of a zval structure or other small memory blocks are requested and freed again. Memory management in PHP has also to respect the memory_limit.
For fulfilling the above requirements the Zend Engine provides a special memory manager for handling request-bound data. Request-bound data is data that is needed only for serving a single request and which will be freed at the request's end at latest. Extension authors will mostly only have contact with the routines listed in the table below. Although they are implemented as macros for providing some convenience features this documentation will treat them like functions.
| Prototype | Description |
|---|---|
void *emalloc(size_t size) |
Allocate size bytes of memory. |
void *ecalloc(size_t nmemb, size_t size) |
Allocate a buffer for nmemb elements of
size bytes and makes sure it is initialized with zeros.
|
void *erealloc(void *ptr, size_t size) |
Resize the buffer ptr, which was allocated using
emalloc to hold size bytes of memory.
|
void efree(void *ptr) |
Free the buffer pointed by ptr. The buffer had to be
allocated by emalloc.
|
void *safe_emalloc(size_t nmemb, size_t size, size_t offset)
|
Allocate a buffer for holding nmemb blocks of each
size bytes and an additional offset bytes.
This is similar to emalloc(nmemb * size + offset) but adds
a special protection against overflows.
|
char *estrdup(const char *s) |
Allocate a buffer that can hold the NULL-terminated string
s and copy the s into that buffer.
|
char *estrndup(const char *s, unsigned int length)
|
Similar to estrdup while the length of the
NULL-terminated string is already known.
|
Note: Unlike their C standard library's counterparts the Zend Engine's memory management functions won't return NULL in case of an problem while allocating the requested memory but bail out and terminate the current request.
As said above it is an essential part of the memory management to avoid
having memory leaks and therefore free all memory you've allocated as soon
as possible. As a safety net the Zend Engine will free all memory, which had
been allocated using above mentioned APIs at the end of a request. If PHP
was built using the --enable-debug configuration option this
will lead to a warning.
Example #1 PHP's leak warnings
ZEND_FUNCTION(leak)
{
long leakbytes = 3;
if (zend_parse_parameters(ZEND_NUM_ARGS() TSRMLS_CC, "|l", &leakbytes) == FAILURE) {
return;
}
emalloc(leakbytes);
}
The above example will output something similar to:
[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 ===
Note: When dealing with PHP variables you have to make sure the variable's memory is allocated using emalloc and take care of the reference count. Details can be found in Working with variables.
Note: This leak detection can only find leaks caused by blocks allocated by emalloc. You're advised to use a memory checker like valgrind or libumem for deeper analysis. To simplify the analysis PHP's memory manager can be disabled by setting the environment variable USE_ZEND_ALLOC=0 before starting PHP.