tvm_ffi.structural_mutate

tvm_ffi.structural_mutate(root, callbacks=())

Mutate a value with callbacks that own recursive mutation.

Each callback receives (value, mutator) and may optionally receive a third inplace_mode integer corresponding to InplaceMode. It equals InplaceMode.ALLOW only when the callback’s value is on a uniquely owned path, and InplaceMode.DISALLOW otherwise. The mode lets a callback choose an ownership-aware implementation; recursive descent uses StructuralMutator.mutate() for selected children or StructuralMutator.default_mutate() for the matched value’s default mutation. Its returned value is final and is not traversed again. Entries use structural_map matching rules, and an unmatched value follows registered/default mutation.

At the outer error boundary, after recursive traversal collects visit context, errors are offered once to the original input root type’s __ffi_enrich_visit_error__(error, root) hook. Only the exact root dynamic type’s attribute is used; parent types are not searched. The hook receives the original input root and returns the original or enriched FFI error. An absent or failing hook leaves the original error unchanged. Recursive visitor/mutator methods only collect context.

Parameters:

• root (Any) – Root value to mutate. Passing a regular Python reference preserves it through copy-on-write; passing root._move() transfers ownership and permits in-place mutation along unique paths.

• callbacks (tuple | Sequence | Callable) – Callback entries tried in order; the first match owns mutation.

Returns:

result – The mutated owning value.

Return type:

Any