Document opcache.huge_code_pages prerequisites when JIT is on - #4861
Open
nisbet-hubbard wants to merge 1 commit into
Open
Document opcache.huge_code_pages prerequisites when JIT is on#4861nisbet-hubbard wants to merge 1 commit into
nisbet-hubbard wants to merge 1 commit into
Conversation
arnaud-lb
requested changes
Jan 9, 2026
arnaud-lb
left a comment
arnaud-lb
left a comment
Member
There was a problem hiding this comment.
@nisbet-hubbard thank you, but I don't think that opcache.huge_code_pages is related to opcache.memory_consumption or opcache.jit_buffer_size: opcache.huge_code_pages only moves the "text segment" of the php binary, aka the php interpreter itself, to huge pages.
It is true that this requires appropriate OS configuration to allocate enough HUGE PAGES for the text segment. I'm not sure how it can be estimated accurately, however. But Opcache will print E_WARNING errors in case moving the text segment fails (as well as debug information in the opcache logs).
lacatoire
reviewed
May 26, 2026
lacatoire
reviewed
May 26, 2026
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
4 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
opcache.huge_code_pages was broken in 8.4 (php/php-src#19638), and has recently been fixed in php/php-src@0ee7732.
It comes with new requirements: in order for PHP to reserve huge pages at all, the OS has to set aside enough to also cover opcache.jit_buffer_size.
This PR documents how to calculate the number to allocate.