Apply was_mutated() rename to native node fast paths

Forward-port the renamed helper and inverted hedge to the tip after the
fast-path restore commit reintroduced the old form during rebase.

Author: adamziel

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

@@ -11,16 +11,15 @@
  * children are never materialized into PHP arrays unless something actually
  * asks for them.
  *
- * The hedge in those methods (`if ( $this->has_unmaterialized_native_ast() )`)
- * is NOT a runtime check for whether the native extension is loaded — if this
- * class is in use, the extension is loaded by definition. It checks whether
- * THIS specific node still has an authoritative native AST behind it. A node
- * loses its native backing the first time it is mutated from PHP via
- * `append_child()` or `merge_fragment()`: those overrides call
- * `materialize_native_children()`, which copies the native children into the
- * inherited `$children` array and then drops the native AST reference. From
- * that point on, the node is a plain PHP-backed `WP_Parser_Node` and the read
- * methods fall through to the parent implementation.
+ * The hedge in those methods (`if ( $this->was_mutated() )`) is NOT a runtime
+ * check for whether the native extension is loaded — if this class is in use,
+ * the extension is loaded by definition. It checks whether THIS specific node
+ * has been mutated from PHP. A node loses its native backing the first time
+ * `append_child()` or `merge_fragment()` is called on it: those overrides
+ * invoke `materialize_native_children()`, which copies the native children
+ * into the inherited `$children` array and drops the native AST reference.
+ * From that point on, the node is a plain PHP-backed `WP_Parser_Node` and the
+ * read methods fall through to the parent implementation.
  *
  * Mutation from PHP is real and intentional — query rewriters in
  * `WP_PDO_MySQL_On_SQLite` (e.g. building synthetic `count(*)` expressions)
@@ -31,6 +30,7 @@
 class WP_MySQL_Native_Parser_Node extends WP_Parser_Node {
 	private $native_ast        = null;
 	private $native_node_index = null;
+	private $was_mutated       = false;
 
 	public function __construct( $rule_id, $rule_name, $native_ast = null, $native_node_index = null ) {
 		parent::__construct( $rule_id, $rule_name );
@@ -67,145 +67,145 @@ public function merge_fragment( $node ) {
 
 	/** @inheritDoc */
 	public function has_child(): bool {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_has_child( $this->native_ast, $this->native_node_index );
+		if ( $this->was_mutated() ) {
+			return parent::has_child();
 		}
-		return parent::has_child();
+		return wp_sqlite_mysql_native_ast_has_child( $this->native_ast, $this->native_node_index );
 	}
 
 	/** @inheritDoc */
 	public function has_child_node( ?string $rule_name = null ): bool {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_has_child_node( $this->native_ast, $this->native_node_index, $rule_name );
+		if ( $this->was_mutated() ) {
+			return parent::has_child_node( $rule_name );
 		}
-		return parent::has_child_node( $rule_name );
+		return wp_sqlite_mysql_native_ast_has_child_node( $this->native_ast, $this->native_node_index, $rule_name );
 	}
 
 	/** @inheritDoc */
 	public function has_child_token( ?int $token_id = null ): bool {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_has_child_token( $this->native_ast, $this->native_node_index, $token_id );
+		if ( $this->was_mutated() ) {
+			return parent::has_child_token( $token_id );
 		}
-		return parent::has_child_token( $token_id );
+		return wp_sqlite_mysql_native_ast_has_child_token( $this->native_ast, $this->native_node_index, $token_id );
 	}
 
 	/** @inheritDoc */
 	public function get_first_child() {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_first_child( $this->native_ast, $this->native_node_index );
+		if ( $this->was_mutated() ) {
+			return parent::get_first_child();
 		}
-		return parent::get_first_child();
+		return wp_sqlite_mysql_native_ast_get_first_child( $this->native_ast, $this->native_node_index );
 	}
 
 	/** @inheritDoc */
 	public function get_first_child_node( ?string $rule_name = null ): ?WP_Parser_Node {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_first_child_node( $this->native_ast, $this->native_node_index, $rule_name );
+		if ( $this->was_mutated() ) {
+			return parent::get_first_child_node( $rule_name );
 		}
-		return parent::get_first_child_node( $rule_name );
+		return wp_sqlite_mysql_native_ast_get_first_child_node( $this->native_ast, $this->native_node_index, $rule_name );
 	}
 
 	/** @inheritDoc */
 	public function get_first_child_token( ?int $token_id = null ): ?WP_Parser_Token {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_first_child_token( $this->native_ast, $this->native_node_index, $token_id );
+		if ( $this->was_mutated() ) {
+			return parent::get_first_child_token( $token_id );
 		}
-		return parent::get_first_child_token( $token_id );
+		return wp_sqlite_mysql_native_ast_get_first_child_token( $this->native_ast, $this->native_node_index, $token_id );
 	}
 
 	/** @inheritDoc */
 	public function get_first_descendant_node( ?string $rule_name = null ): ?WP_Parser_Node {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_first_descendant_node( $this->native_ast, $this->native_node_index, $rule_name );
+		if ( $this->was_mutated() ) {
+			return parent::get_first_descendant_node( $rule_name );
 		}
-		return parent::get_first_descendant_node( $rule_name );
+		return wp_sqlite_mysql_native_ast_get_first_descendant_node( $this->native_ast, $this->native_node_index, $rule_name );
 	}
 
 	/** @inheritDoc */
 	public function get_first_descendant_token( ?int $token_id = null ): ?WP_Parser_Token {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_first_descendant_token( $this->native_ast, $this->native_node_index, $token_id );
+		if ( $this->was_mutated() ) {
+			return parent::get_first_descendant_token( $token_id );
 		}
-		return parent::get_first_descendant_token( $token_id );
+		return wp_sqlite_mysql_native_ast_get_first_descendant_token( $this->native_ast, $this->native_node_index, $token_id );
 	}
 
 	/** @inheritDoc */
 	public function get_children(): array {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_children( $this->native_ast, $this->native_node_index );
+		if ( $this->was_mutated() ) {
+			return parent::get_children();
 		}
-		return parent::get_children();
+		return wp_sqlite_mysql_native_ast_get_children( $this->native_ast, $this->native_node_index );
 	}
 
 	/** @inheritDoc */
 	public function get_child_nodes( ?string $rule_name = null ): array {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_child_nodes( $this->native_ast, $this->native_node_index, $rule_name );
+		if ( $this->was_mutated() ) {
+			return parent::get_child_nodes( $rule_name );
 		}
-		return parent::get_child_nodes( $rule_name );
+		return wp_sqlite_mysql_native_ast_get_child_nodes( $this->native_ast, $this->native_node_index, $rule_name );
 	}
 
 	/** @inheritDoc */
 	public function get_child_tokens( ?int $token_id = null ): array {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_child_tokens( $this->native_ast, $this->native_node_index, $token_id );
+		if ( $this->was_mutated() ) {
+			return parent::get_child_tokens( $token_id );
 		}
-		return parent::get_child_tokens( $token_id );
+		return wp_sqlite_mysql_native_ast_get_child_tokens( $this->native_ast, $this->native_node_index, $token_id );
 	}
 
 	/** @inheritDoc */
 	public function get_descendants(): array {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_descendants( $this->native_ast, $this->native_node_index );
+		if ( $this->was_mutated() ) {
+			return parent::get_descendants();
 		}
-		return parent::get_descendants();
+		return wp_sqlite_mysql_native_ast_get_descendants( $this->native_ast, $this->native_node_index );
 	}
 
 	/** @inheritDoc */
 	public function get_descendant_nodes( ?string $rule_name = null ): array {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_descendant_nodes( $this->native_ast, $this->native_node_index, $rule_name );
+		if ( $this->was_mutated() ) {
+			return parent::get_descendant_nodes( $rule_name );
 		}
-		return parent::get_descendant_nodes( $rule_name );
+		return wp_sqlite_mysql_native_ast_get_descendant_nodes( $this->native_ast, $this->native_node_index, $rule_name );
 	}
 
 	/** @inheritDoc */
 	public function get_descendant_tokens( ?int $token_id = null ): array {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_descendant_tokens( $this->native_ast, $this->native_node_index, $token_id );
+		if ( $this->was_mutated() ) {
+			return parent::get_descendant_tokens( $token_id );
 		}
-		return parent::get_descendant_tokens( $token_id );
+		return wp_sqlite_mysql_native_ast_get_descendant_tokens( $this->native_ast, $this->native_node_index, $token_id );
 	}
 
 	/** @inheritDoc */
 	public function get_start(): int {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_start( $this->native_ast, $this->native_node_index );
+		if ( $this->was_mutated() ) {
+			return parent::get_start();
 		}
-		return parent::get_start();
+		return wp_sqlite_mysql_native_ast_get_start( $this->native_ast, $this->native_node_index );
 	}
 
 	/** @inheritDoc */
 	public function get_length(): int {
-		if ( $this->has_unmaterialized_native_ast() ) {
-			return wp_sqlite_mysql_native_ast_get_length( $this->native_ast, $this->native_node_index );
+		if ( $this->was_mutated() ) {
+			return parent::get_length();
 		}
-		return parent::get_length();
+		return wp_sqlite_mysql_native_ast_get_length( $this->native_ast, $this->native_node_index );
 	}
 
 	/**
-	 * Indicates whether this node still has an unmaterialized native AST.
+	 * Indicates whether this node has been mutated from PHP.
 	 *
-	 * Returns true for freshly-parsed nodes whose children live in the
-	 * Rust-owned AST buffer; returns false once the node has been mutated and
-	 * its children copied into the inherited `$children` array (see
-	 * self::materialize_native_children()).
+	 * Returns false for freshly-parsed nodes whose children still live in the
+	 * Rust-owned AST buffer; returns true once `append_child()` or
+	 * `merge_fragment()` has copied the children into the inherited
+	 * `$children` array and dropped the native AST reference.
 	 *
 	 * This is a per-instance state check, not a check for whether the native
 	 * extension is loaded.
 	 */
-	private function has_unmaterialized_native_ast(): bool {
-		return null !== $this->native_ast;
+	private function was_mutated(): bool {
+		return $this->was_mutated;
 	}
 
 	/**
@@ -214,16 +214,17 @@ private function has_unmaterialized_native_ast(): bool {
 	 *
 	 * Called before any mutation (append_child, merge_fragment) so the node's
 	 * authoritative state lives in PHP from that point on. After this runs,
-	 * has_unmaterialized_native_ast() returns false and read methods fall
-	 * through to the parent WP_Parser_Node implementation.
+	 * was_mutated() returns true and read methods fall through to the parent
+	 * WP_Parser_Node implementation.
 	 */
 	private function materialize_native_children(): void {
-		if ( ! $this->has_unmaterialized_native_ast() ) {
+		if ( $this->was_mutated ) {
 			return;
 		}
 
 		$this->children          = wp_sqlite_mysql_native_ast_get_children( $this->native_ast, $this->native_node_index );
 		$this->native_ast        = null;
 		$this->native_node_index = null;
+		$this->was_mutated       = true;
 	}
 }