Skip to content

add details about optimizer passes #4858

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
+164 −6
Open

add details about optimizer passes #4858

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ee63d8d
add details about optimizer passes
realFlowControl Sep 3, 2025
e4cb040
update from review
realFlowControl Sep 4, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 164 additions & 6 deletions reference/opcache/ini.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -592,10 +592,155 @@
<listitem>
<para>
A bitmask that controls which optimisation passes are executed.
The default is to apply all safe optimizations.
Changing the default is mostly useful for debugging/developing the optimizer
(see also <link linkend="ini.opcache.opt_debug_level">opcache.opt_debug_level</link>).
</para>
The default value is <literal>0x7FFEBFFF</literal>, which enables all
safe optimizations. Disabling optimizations or enabling unsafe optimizations
is mostly useful for debugging/developing the optimizer.
</para>
<para>
Each bit in the bitmask enables a specific optimization pass:
</para>
<table>
<title>Optimization Pass Bitmask</title>
<tgroup cols="6">
<thead>
<row>
<entry>Bit</entry>
<entry>Pass Name</entry>
<entry>Description</entry>
<entry>Default</entry>
</row>
</thead>
<tbody>
<row>
<entry>0</entry>
<entry>PASS_1</entry>
<entry>Simple peephole optimizations</entry>
<entry>On</entry>
</row>
<row>
<entry>1</entry>
<entry>PASS_2</entry>
<entry>Unused (got merged into PASS_1)</entry>
<entry>On</entry>
</row>
<row>
<entry>2</entry>
<entry>PASS_3</entry>
<entry>Simple jump optimization</entry>
<entry>On</entry>
</row>
<row>
<entry>3</entry>
<entry>PASS_4</entry>
<entry>Call optimization</entry>
<entry>On</entry>
</row>
<row>
<entry>4</entry>
<entry>PASS_5</entry>
<entry>Control Flow Graph based optimization</entry>
<entry>On</entry>
</row>
<row>
<entry>5</entry>
<entry>PASS_6</entry>
<entry>Data Flow Analysis based optimization</entry>
<entry>On</entry>
</row>
<row>
<entry>6</entry>
<entry>PASS_7</entry>
<entry>Whether call graph should be used for SSA-based optimizations</entry>
<entry>On</entry>
</row>
<row>
<entry>7</entry>
<entry>PASS_8</entry>
<entry>Sparse conditional constant propagation</entry>
<entry>On</entry>
</row>
<row>
<entry>8</entry>
<entry>PASS_9</entry>
<entry>Temporary variable optimization</entry>
<entry>On</entry>
</row>
<row>
<entry>9</entry>
<entry>PASS_10</entry>
<entry>Removal of NOP opcodes</entry>
<entry>On</entry>
</row>
<row>
<entry>10</entry>
<entry>PASS_11</entry>
<entry>Literal optimization</entry>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: Literal compaction

<entry>On</entry>
</row>
<row>
<entry>11</entry>
<entry>PASS_12</entry>
<entry>Call stack adjustment</entry>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggest: Pre-compute call stack size

<entry>On</entry>
</row>
<row>
<entry>12</entry>
<entry>PASS_13</entry>
<entry>Unused variable removal</entry>
<entry>On</entry>
</row>
<row>
<entry>13</entry>
<entry>PASS_14</entry>
<entry>Dead code elimination</entry>
<entry>On</entry>
</row>
<row>
<entry>14</entry>
<entry>PASS_15</entry>
<entry>Collect and substitute constant declarations (unsafe)</entry>
<entry><emphasis>Off</emphasis></entry>
</row>
<row>
<entry>15</entry>
<entry>PASS_16</entry>
<entry>Trivial function inlining (part of call optimization)</entry>
<entry>On</entry>
</row>
<row>
<entry>16</entry>
<entry>(Flag)</entry>
<entry>Ignore possibility of operator overloading (unsafe)</entry>
<entry><emphasis>Off</emphasis></entry>
</row>
</tbody>
</tgroup>
</table>
<note>
<title>Safe vs Unsafe Optimizations</title>
<para>
<emphasis>Safe optimizations</emphasis> (enabled by default) preserve the exact
behavior of PHP code while improving performance. They include dead code elimination,
constant folding, and jump optimization.
</para>
<para>
<emphasis>Unsafe optimizations</emphasis> (disabled by default) may alter behavior
in edge cases:
</para>
<itemizedlist>
<listitem>
<para>
<emphasis>Bit 14</emphasis>: Aggressive constant collection may not preserve
exact behavior in all cases
</para>
</listitem>
<listitem>
<para>
<emphasis>Bit 16</emphasis>: Ignoring operator overloading
</para>
</listitem>
</itemizedlist>
</note>
</listitem>
</varlistentry>
<varlistentry xml:id="ini.opcache.inherited-hack">
Expand Down Expand Up @@ -843,8 +988,21 @@
<listitem>
<para>
Produces opcode dumps for debugging different stages of optimizations.
0x10000 will output opcodes as the compiler produced them before any optimization occurs
while 0x20000 will output optimized codes.
Accepts bit flags from <link linkend="ini.opcache.optimization-level">
opcache.optimization_level</link> for optimization passes, plus
additional debugging dump points:
</para>
<simplelist>
<member><code>0x10000</code>: Dump before optimizer</member>
<member><code>0x20000</code>: Dump after optimizer</member>
<member><code>0x40000</code>: Dump before CFG optimizations</member>
<member><code>0x80000</code>: Dump after CFG optimizations</member>
<member><code>0x200000</code>: Dump before SSA optimizations</member>
<member><code>0x400000</code>: Dump after SSA optimizations</member>
</simplelist>
<para>
Setting <code>opcache.opt_debug_level=-1</code> produces a full trace
through all optimization stages.
</para>
</listitem>
</varlistentry>
Expand Down