Basic memory management

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.

**Main memory APIs**
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.