Add direct-return fast path for single-candidate rules

On the MySQL grammar, 1,290 of 1,916 rules have a selector where every
(rule, token) entry points to exactly one branch. Those rules account
for ~55% of parse_recursive calls on the test corpus (722k of 1.3M per
10k queries).

Flag those rules at grammar build time. In parse_recursive, detect the
flag and take the only candidate branch directly, skipping the
candidate-iteration loop. On match failure, restore $position and
return false directly instead of going through the multi-candidate
branch_matches/break sequence.

End-to-end parser benchmark:
  no JIT:      ~31.6K -> ~32.6K QPS avg (+3%)
  tracing JIT: ~52.6K -> ~55.7K QPS avg (+6%)

Author: JanJakes

packages/mysql-on-sqlite/src/parser/class-wp-parser-grammar.php

@@ -55,6 +55,15 @@ class WP_Parser_Grammar {
 	 */
 	public $nullable_branches = array();
 
+	/**
+	 * Per-rule flag indicating every (rule, token) selector entry points
+	 * to exactly one branch. The parser uses this to skip the outer
+	 * foreach when a single candidate is the only possibility.
+	 *
+	 * @var array<int,true>
+	 */
+	public $single_candidate_rules = array();
+
 	public $lowest_non_terminal_id;
 	public $highest_terminal_id;
 
@@ -345,8 +354,12 @@ private function build_branch_selectors() {
 				// copy-on-write share one sequences array across all of
 				// them. Without this the nested table would be ~40 MB; with
 				// it, ~1 MB.
-				$by_signature = array();
+				$by_signature          = array();
+				$all_single_candidates = true;
 				foreach ( $selector as $tid => $idx_list ) {
+					if ( 1 !== count( $idx_list ) ) {
+						$all_single_candidates = false;
+					}
 					$sig = implode( ',', $idx_list );
 					if ( isset( $by_signature[ $sig ] ) ) {
 						$selector[ $tid ] = $by_signature[ $sig ];
@@ -360,6 +373,9 @@ private function build_branch_selectors() {
 					}
 				}
 				$this->branches_for_token[ $rule_id ] = $selector;
+				if ( $all_single_candidates ) {
+					$this->single_candidate_rules[ $rule_id ] = true;
+				}
 			}
 		}
 	}

packages/mysql-on-sqlite/src/parser/class-wp-parser.php

@@ -22,6 +22,7 @@ class WP_Parser {
 	private $nullable_branches;
 	private $highest_terminal_id;
 	private $select_statement_rule_id;
+	private $single_candidate_rules;
 
 	public function __construct( WP_Parser_Grammar $grammar, array $tokens ) {
 		$this->grammar     = $grammar;
@@ -31,14 +32,15 @@ public function __construct( WP_Parser_Grammar $grammar, array $tokens ) {
 		// when $pos is the current cursor, because the sentinel naturally
 		// fails to match any real grammar terminal while feeding the
 		// nullable-fallback branch of the selector check.
-		$tokens[]                  = new WP_Parser_Token( WP_Parser_Grammar::EMPTY_RULE_ID, 0, 0, '' );
-		$this->tokens              = $tokens;
-		$this->position            = 0;
-		$this->rule_names          = $grammar->rule_names;
-		$this->fragment_ids        = $grammar->fragment_ids ?? array();
-		$this->branches_for_token  = $grammar->branches_for_token;
-		$this->nullable_branches   = $grammar->nullable_branches;
-		$this->highest_terminal_id = $grammar->highest_terminal_id;
+		$tokens[]                     = new WP_Parser_Token( WP_Parser_Grammar::EMPTY_RULE_ID, 0, 0, '' );
+		$this->tokens                 = $tokens;
+		$this->position               = 0;
+		$this->rule_names             = $grammar->rule_names;
+		$this->fragment_ids           = $grammar->fragment_ids ?? array();
+		$this->branches_for_token     = $grammar->branches_for_token;
+		$this->nullable_branches      = $grammar->nullable_branches;
+		$this->highest_terminal_id    = $grammar->highest_terminal_id;
+		$this->single_candidate_rules = $grammar->single_candidate_rules ?? array();
 
 		// The INTO negative-lookahead only fires for selectStatement. Cache
 		// the rule id so the per-call check is an int compare instead of a
@@ -89,8 +91,61 @@ private function parse_recursive( $rule_id ) {
 		$highest_terminal_id = $this->highest_terminal_id;
 		$is_fragment         = isset( $this->fragment_ids[ $rule_id ] );
 		$is_select_statement = $rule_id === $this->select_statement_rule_id;
-		$branch_matches      = false;
-		$children            = array();
+
+		// Fast path for rules where every (rule, token) selector entry
+		// points to exactly one branch - about 55% of nonterminal calls
+		// on the MySQL corpus. Skipping the outer foreach avoids the
+		// foreach iterator setup for those calls.
+		if ( isset( $this->single_candidate_rules[ $rule_id ] ) ) {
+			// Single-candidate fast path: the rule has exactly one branch
+			// to try for this token, so skip the outer foreach and the
+			// $branch_matches bookkeeping - every failure path just
+			// rewinds the position and returns false directly.
+			$branch   = $candidate_branches[0];
+			$children = array();
+			foreach ( $branch as $subrule_id ) {
+				if ( $subrule_id <= $highest_terminal_id ) {
+					if ( $tokens[ $this->position ]->id === $subrule_id ) {
+						$children[] = $tokens[ $this->position ];
+						++$this->position;
+						continue;
+					}
+					$this->position = $position;
+					return false;
+				}
+
+				$subnode = $this->parse_recursive( $subrule_id );
+				if ( false === $subnode ) {
+					$this->position = $position;
+					return false;
+				}
+				if ( true === $subnode ) {
+					continue;
+				}
+				if ( is_array( $subnode ) ) {
+					foreach ( $subnode as $c ) {
+						$children[] = $c;
+					}
+				} else {
+					$children[] = $subnode;
+				}
+			}
+
+			if ( $is_select_statement && WP_MySQL_Lexer::INTO_SYMBOL === $tokens[ $this->position ]->id ) {
+				$this->position = $position;
+				return false;
+			}
+			if ( ! $children ) {
+				return true;
+			}
+			if ( $is_fragment ) {
+				return $children;
+			}
+			return new WP_Parser_Node( $rule_id, $this->rule_names[ $rule_id ], $children );
+		}
+
+		$branch_matches = false;
+		$children       = array();
 		foreach ( $candidate_branches as $branch ) {
 			$this->position = $position;
 			$children       = array();