[doc-en] master: memory-get-usage.xml Clarify what kind of memory we are talking about (#4491)

Author: Mikhail Alferov (mmalferov) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-03T12:00:44+02:00 Commit: https://github.com/php/doc-en/commit/f78a9528a2fe8e78380fb28cacbe6e152fa4bb6d Raw diff: https://github.com/php/doc-en/commit/f78a9528a2fe8e78380fb28cacbe6e152fa4bb6d.diff memory-get-usage.xml Clarify what kind of memory we are talking about (#4491) * memory-get-usage.xml Clarify what kind of memory we are talking about The current description confuses the reader and does not explain who allocates memory to whom. I'm not sure about the accuracy of the proposed formulations, but it seems that the changes better explain the difference between function calls without arguments or with the value false, or with the argument true. I think that mentioning the engine, Zend Memory Manager (ZMM), or other internal details would be redundant, and the current description is enough to understand the difference. Please check the proposal and make corrections to eliminate linguistic or semantic inaccuracies, if any, in the updated text. And if the suggestion is OK, I will make the same changes with memory_get_peak_usage() ;-) * Update reference/info/functions/memory-get-usage.xml Co-authored-by: Larry Garfield <larry@garfieldtech.com> * memory_get_usage(): describe what the two values actually measure Neither value is memory the operating system has given to the process. memory_get_usage(true) returns the size of the chunks PHP's memory manager has reserved, which is what memory_limit is enforced against; on a freshly started script it reports 2 MB while the process already has ~25 MB resident. And memory_get_usage(false) counts allocations rounded up to the allocator's granularity rather than the bytes the script asked for, so "allocated" is the accurate word, not "using". The note keeps saying what is not counted, since that is the part a reader needs, and now says that real_usage does not escape it either. --------- Co-authored-by: Larry Garfield <larry@garfieldtech.com> Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M reference/info/functions/memory-get-usage.xml Diff: diff --git a/reference/info/functions/memory-get-usage.xml b/reference/info/functions/memory-get-usage.xml index 1d2e401efaf6..b74650682c31 100644 --- a/reference/info/functions/memory-get-usage.xml +++ b/reference/info/functions/memory-get-usage.xml @@ -3,39 +3,55 @@ <refentry xml:id="function.memory-get-usage" xmlns="http://docbook.org/ns/docbook"> <refnamediv> <refname>memory_get_usage</refname> - <refpurpose>Returns the amount of memory allocated to PHP</refpurpose> + <refpurpose> + Returns the amount of memory allocated to the PHP script, or reserved + from the system by PHP's memory manager + </refpurpose> </refnamediv> - + <refsect1 role="description"> &reftitle.description; <methodsynopsis> <type>int</type><methodname>memory_get_usage</methodname> <methodparam choice="opt"><type>bool</type><parameter>real_usage</parameter><initializer>&false;</initializer></methodparam> </methodsynopsis> - <para> - Returns the amount of memory, in bytes, that's currently being - allocated to your PHP script. - </para> + <simpara> + Returns the amount of memory, in bytes, that is currently allocated to + the PHP script by PHP's memory manager. The reported value is rounded up + to the granularity of the allocator, so it is larger than the exact + number of bytes that were requested. + </simpara> </refsect1> <refsect1 role="parameters"> &reftitle.parameters; - <para> - <variablelist> - <varlistentry> - <term><parameter>real_usage</parameter></term> - <listitem> - <para> - Set this to &true; to get total memory allocated from - system, including unused pages. - If not set or &false; only the used memory is reported. - </para> - </listitem> - </varlistentry> - </variablelist> - </para> + <variablelist> + <varlistentry> + <term><parameter>real_usage</parameter></term> + <listitem> + <simpara> + Set this to &true; to get the total amount of memory that PHP's memory + manager has reserved from the system, including pages that are not + currently in use. This is the value that + <link linkend="ini.memory-limit">memory_limit</link> is enforced + against. It is not the amount of memory the operating system has given + to the PHP process, which is typically much larger. + </simpara> + <simpara> + If not set or &false; only the memory currently allocated to the PHP + script is reported. + </simpara> + </listitem> + </varlistentry> + </variablelist> <note> - <para>PHP does not track memory that is not allocated by <literal>emalloc()</literal></para> + <simpara> + PHP only tracks memory allocated through its own memory manager, that is + through the internal <literal>emalloc()</literal> function and the related + ones. Memory allocated persistently, or directly with + <literal>malloc()</literal> by an extension, is not reported, even when + <parameter>real_usage</parameter> is &true;. + </simpara> </note> </refsect1> @@ -54,18 +70,19 @@ <programlisting role="php"> <![CDATA[ <?php + // This is only an example, the numbers below will -// differ depending on your system +// differ depending on the specific system -echo memory_get_usage() . "\n"; // 36640 +echo memory_get_usage(), "\n"; // 36640 $a = str_repeat("Hello", 4242); -echo memory_get_usage() . "\n"; // 57960 +echo memory_get_usage(), "\n"; // 57960 unset($a); -echo memory_get_usage() . "\n"; // 36744 +echo memory_get_usage(), "\n"; // 36744 ?> ]]>