Class StructuralMutatorObj

Class StructuralMutatorObj#

Inheritance Relationships#

Base Type#

Derived Type#

Class Documentation#

class StructuralMutatorObj : public tvm::ffi::Object#

Object node of a structural mutator.

Subclassed by tvm::ffi::StructuralMapEngineBase

Public Types

using MutatorObjType = StructuralMutatorObj#

Callback-facing mutator type used by composed callback-driven engines.

Public Functions

inline UnchangedOr<Any> Mutate(AnyView value, InplaceMode inplace_mode = InplaceMode::kDisallow)#

Throwing form of MutateExpected.

Use TVM_FFI_S_MUTATE_ASSIGN_OR_RETURN in Expected-returning helpers or raw hooks to preserve checked typed mutation results and the fixed mismatch diagnostic. At a throwing boundary, an explicit cast may instead report its own TypeError: 

Expr new_node = mutator->Mutate(node).ValueOrUnchanged(AnyView(node)).cast<Expr>();

Note

The default InplaceMode::kDisallow uses copy-on-write. In-place mutation is permitted only when inplace_mode is InplaceMode::kAllow and the current value is uniquely owned. See MutateExpected for the full permission and error semantics.

Parameters:

  • value – The borrowed value to mutate.

  • inplace_mode – Whether the caller permits mutation along this ownership path.

Throws:

Error – if mutation fails.

Returns:

The replacement or unchanged marker.

inline Expected<UnchangedOr<Any>> MutateExpected(AnyView value, InplaceMode inplace_mode = InplaceMode::kDisallow) noexcept#

Mutate a value, permitting in-place mutation only when uniquely owned.

Note

The default InplaceMode::kDisallow uses copy-on-write. In-place mutation is permitted only when inplace_mode is InplaceMode::kAllow and the current value is uniquely owned. InplaceMode::kAllow requires permission along the entire path from the root. Recursive calls must forward their established mode explicitly. Uniqueness is checked before callback arguments acquire ownership. This permits in-place dispatch but does not guarantee reuse: a hook may return a replacement. In-place changes completed before an Error are not rolled back.

Parameters:

  • value – The borrowed value to mutate.

  • inplace_mode – Whether the caller permits mutation along this ownership path.

Returns:

The replacement or unchanged marker, or an Error if mutation failed.

inline Expected<UnchangedOr<Any>> DefaultMutateExpected(AnyView value, InplaceMode inplace_mode = InplaceMode::kDisallow) noexcept#

Apply default structural mutation with validated in-place permission.

Note

The default InplaceMode::kDisallow is a copy-on-write convenience for one-off calls. Recursive code and hooks must explicitly forward the mode established for the current value. This method uses that mode without checking uniqueness again, even if a typed callback argument has acquired another reference. It bypasses the current engine callback. Permission must cover the entire path from the root. Without an in-place hook, ordinary mutation runs. In-place changes completed before an Error are not rolled back. Registered hooks own variable-remap handling; the reflected fallback applies it automatically and always uses copy-on-write mutation.

Parameters:

  • value – The borrowed current value to mutate.

  • inplace_mode – The in-place mode already established by the caller for value.

Returns:

The replacement or unchanged marker, or an Error if mutation failed.

inline Expected<Any> VarRemapGetExpected(AnyView var) noexcept#

Look up the replacement recorded for a variable identity.

Note

The identity must have kTVMFFISEqHashKindFreeVar or kTVMFFISEqHashKindDAGNode structural-equality metadata.

Parameters:

var – The borrowed variable identity to look up.

Returns:

The owning replacement, FFI None if no replacement exists, or an Error if lookup fails.

inline Expected<void> VarRemapSetExpected(AnyView var, AnyView mapped_value) noexcept#

Record the replacement for a variable identity.

Note

The identity must have kTVMFFISEqHashKindFreeVar or kTVMFFISEqHashKindDAGNode structural-equality metadata.

Parameters:

  • var – The borrowed variable identity to bind.

  • mapped_value – The borrowed replacement value.

Returns:

Successful completion, or an Error if the binding is invalid or cannot be stored.

inline TVMFFIDefRegionKind def_region_kind() const#

Return the current def-region context.

Note

A custom mutate hook for a FreeVar type must apply the simple-def clamp itself: when this is kTVMFFIDefRegionKindSimple, descend the variable’s type under kTVMFFIDefRegionKindNone. The reflected walk does this on its own.

Returns:

The active def-region kind.

template<typename Callback>
inline auto WithDefRegionKind(TVMFFIDefRegionKind kind, Callback &&callback) -> decltype(std::forward<Callback>(callback)())#

Temporarily switch the def-region context while invoking callback.

Note

Inside a pattern region this is a no-op: the pattern propagates, so kind is ignored and the callback runs under the pattern.

Parameters:

  • kind – The def-region kind to set during the callback.

  • callback – A nullary callable that performs recursive mutation.

Returns:

The value returned by callback.

Protected Functions

inline explicit StructuralMutatorObj(const StructuralMutatorVTable *vtable)#

Construct a structural mutator from an immutable dispatch vtable.

Parameters:

vtable – The non-null dispatch table for this mutator. It must outlive this object.

Protected Attributes

const StructuralMutatorVTable *vtable_ = nullptr#

Non-owning pointer to the required ABI dispatch table.

TVMFFIDefRegionKind def_region_mode_ = kTVMFFIDefRegionKindNone#

Current def-region context for def-region-aware structural mutation.