[doc-en] master: Document huge page use by the OPcache shared memory segment (#4861)

Author: nisbet-hubbard (nisbet-hubbard) Committer: GitHub (web-flow) Pusher: lacatoire Date: 2026-09-08T13:30:34+02:00 Commit: https://github.com/php/doc-en/commit/83c44e16897a8f6371b0c652ce9610b396514fb8 Raw diff: https://github.com/php/doc-en/commit/83c44e16897a8f6371b0c652ce9610b396514fb8.diff Document huge page use by the OPcache shared memory segment (#4861) opcache.huge_code_pages only remaps the text segment of the PHP binary: accel_move_code_to_huge_pages() scans /proc/self/maps for the r-x mapping belonging to the running binary and remaps that one. It has no bearing on opcache.memory_consumption or opcache.jit_buffer_size. The shared memory segment is a separate matter, and its use of huge pages was undocumented. Its size is memory_consumption plus jit_buffer_size when the JIT is enabled, and OPcache tries to allocate it with MAP_HUGETLB before falling back to regular pages without any diagnostic. That is what makes the huge page pool appear undersized when the JIT is on. Also states that a failed text segment remap reports an E_WARNING, and that huge_code_pages does not cover the shared memory segment, since the two are easily conflated. Co-authored-by: Louis-Arnaud <la.catoire@gmail.com> Changed paths: M reference/opcache/ini.xml Diff: diff --git a/reference/opcache/ini.xml b/reference/opcache/ini.xml index 966af001f32f..616cb6d3e257 100644 --- a/reference/opcache/ini.xml +++ b/reference/opcache/ini.xml @@ -409,6 +409,14 @@ The minimum permissible value is <literal>"8"</literal>, which is enforced if a smaller value is set. </simpara> + <simpara> + When the JIT is enabled, the shared memory segment also holds the JIT + buffer, so its total size is this value plus + <link linkend="ini.opcache.jit-buffer-size">opcache.jit_buffer_size</link>. + OPcache first attempts to allocate the segment using HUGE PAGES, and + silently falls back to regular pages when the operating system has not + set aside enough of them. + </simpara> </listitem> </varlistentry> <varlistentry xml:id="ini.opcache.interned-strings-buffer"> @@ -977,6 +985,11 @@ function getA() { return A; } <simpara> Enables or disables copying of PHP code (text segment) into HUGE PAGES. This should improve performance, but requires appropriate OS configuration. + Only the text segment of the PHP binary is remapped; the shared memory + segment described under + <link linkend="ini.opcache.memory-consumption">opcache.memory_consumption</link> + is unaffected by this directive. When the remapping fails, OPcache emits + an <constant>E_WARNING</constant>. Available on Linux as of PHP 7.0.0, and on FreeBSD as of PHP 7.4.0. </simpara> </listitem>