Template Function tvm::ffi::StructuralMapExpected

Template Function tvm::ffi::StructuralMapExpected#

Function Documentation#

template<WalkOrder order, typename ...Callbacks>
Expected<Any> tvm::ffi::StructuralMapExpected(Any root, Callbacks&&... callbacks) noexcept#

Structural map: mutate(x) = post(D(pre(x))).

D is descent with a var remap that keeps the result consistent when a var is rewritten as a cascade effect of its fields changing during descent. Callbacks never read or write D’s remap cache, and fire once per occurrence in whichever position they sit.

Var policy in default D: each var is descended at most once in def (its first occurrence in a pattern def, its only occurrence in a simple def), and then returns the new rewritten result if any in use. Definitions are assumed to precede uses; a var with no definition is treated as a use.

Canonical use cases include:

  • use pre for var replacement to another value or var

  • for a tree node, a post rewrite after its children are mapped

A callback is selected by its first argument type, optionally followed by TVMFFIDefRegionKind; the first match in declaration order runs. It returns a replacement, Unchanged, or Expected<U>, and must not mutate its input. A post-order callback is selected by the type of what descent produced.

Note

For a DAG type node, post callback fires at every of its occurrences, so if the intent is to do graph rewrite, post callback needs to have its own node to value memo; the engine does not dedup callback rewrites.

Template Parameters:

  • order – Whether callbacks run before or after mapping children.

  • Callbacks – Callback types whose first parameters select matching values.

Parameters:

  • root – The owning root value to map; pass std::move(root) to permit reuse.

  • callbacks – Callbacks tested in declaration order.

Returns:

The mapped owning value, or an Error if mapping or a callback fails.