From b3a256290a122e082175ce6fd45a2f25cefe32f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Johannes=20Schl=C3=BCter?= Date: Mon, 26 Oct 2009 22:44:53 +0000 Subject: [PATCH] Basic documentation about memory management in PHP # native speakers feel free to fix grammer, spelling, ... :-) git-svn-id: https://svn.php.net/repository/phpdoc/en/trunk@289963 c90b9560-bf6c-de11-be94-00142212c4b1 --- internals2/memory/management.xml | 188 ++++++++++++++++++++++++++++++- 1 file changed, 185 insertions(+), 3 deletions(-) diff --git a/internals2/memory/management.xml b/internals2/memory/management.xml index b1baeab34f..80c6962a72 100644 --- a/internals2/memory/management.xml +++ b/internals2/memory/management.xml @@ -3,7 +3,189 @@ 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 , + which serves as thread-isolation facility. + - \ No newline at end of file + + 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. + + + + +
+ + + + Unlike their C stdandad 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 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. + + + + PHP's leak warnings + + + + &example.outputs.similar; + + + + + + + + When dealing with PHP variables you have to make sure the variable is + allocated using emalloc and take care of the reference count. Details can + be found in . + + + + + + 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. + + + + + +