Template Function tvm::ffi::StructuralMutateExpected

Template Function tvm::ffi::StructuralMutateExpected#

Function Documentation#

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

Mutate a structured value with callbacks that own recursion.

A callback takes one of two forms, where R is a supported return type:

  • R(const T& value, StructuralMutatorObj* mutator)

  • R(const T& value, StructuralMutatorObj* mutator, InplaceMode inplace_mode)

A callback returns a replacement, Unchanged, or Expected<Any>. The first argument selects by FFI type; callbacks are tried in declaration order and the first match owns mutation &#8212; it drives its own recursion through the mutator and sets any variable remapping. An unmatched value takes registered or reflected default mutation.

Note

A two-argument callback descends with MutateExpected(value), using the default copy-on-write permission. A three-argument callback receives InplaceMode::kAllow only when its value is on a uniquely owned path. Forward this mode to MutateExpected for child values or DefaultMutateExpected for the current value’s default descent.

Note

Pass an owned root with std::move(root) to permit root reuse. In a __s_maybe_inplace_mutate__ hook, the corresponding nested idiom is self->field = StructuralMap(std::move(self->field), callback); const-correctness rejects that ownership transfer outside a mutable maybe-in-place hook.

Parameters:

  • root – The owning root value to mutate.

  • callbacks – Callbacks tested in declaration order.

Returns:

The mutated owning value, or an Error if mutation or a callback fails.