Class ObjectMutator

Class ObjectMutator#

Inheritance Relationships#

Base Type#

  • public tvm::ffi::StructuralMapEngineBase

Derived Type#

Class Documentation#

class ObjectMutator : public tvm::ffi::StructuralMapEngineBase#

Native mutation with exact dispatch and structural fallback.

Allocate mutators with ffi::make_object<Derived>(). Inputs are borrowed; replacements and errors own their values. Overrides forward inplace_mode to child calls, following the structural mutation ownership contract.

Subclassed by tvm::ExprMutator

Public Functions

inline ObjectMutator()#

Construct a mutator using structural fallback for every object.

ObjectMutator(const ObjectMutator &other) = delete#
ObjectMutator &operator=(const ObjectMutator &other) = delete#
inline virtual UnchangedOr<ffi::Any> Mutate(ffi::AnyView value, InplaceMode inplace_mode = InplaceMode::kDisallow)#

Mutate a borrowed value, throwing on failure.

In-place mutation requires every node and owning container on the root-to-current path to be unique. Inherited inplace_mode records ancestor permission; Mutate checks the current target. Never promote inherited denial to permission. Within a Mutate_ hook, forward mode to a parent hook or an immediate child: 

Parent_::Mutate_(node, mode);  // The current node was already checked.
Mutate(node->elem, mode);     // Mutate checks elem's uniqueness.
Direct descent that skips an owning ancestor must check that ancestor too: 
auto child_mode = node->elem.unique() ? mode : InplaceMode::kDisallow;
Mutate(node->elem->a, child_mode);
When in doubt, omit inplace_mode. The default kDisallow is always safe; pass permission explicitly only when the full ancestor path is accounted for.

Note

Establishes uniqueness before invoking typed hooks. Entry overrides must preserve inherited denial and check uniqueness before writing or forwarding permission. Qualified Parent::Mutate bypasses the current override while descendants remain virtual. Completed in-place changes are not rolled back on error.

Parameters:

  • value – The borrowed object or inline value to mutate.

  • inplace_mode – Inherited permission along the path to this value.

Returns:

An owning replacement or Unchanged. Non-object inputs return their inline value.

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

Adapt the virtual throwing entrypoint to the structural ABI.

Note

Matches the FFI safe-call exception contract. Error identity is preserved; other standard exceptions become InternalError.

Parameters:

  • value – The borrowed value to mutate.

  • inplace_mode – Inherited mutation permission.

Returns:

The replacement, Unchanged, or the caught error.

inline ffi::Any VarRemapGet(ffi::AnyView var)#

Look up a variable replacement, throwing on failure.

inline void VarRemapSet(ffi::AnyView var, ffi::AnyView value)#

Record a variable replacement, throwing on failure.

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

Look up a replacement in the variable-remap environment.

Parameters:

var – The borrowed variable identity to look up.

Returns:

The owning replacement, None on a miss, or an Error.

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

Record a replacement in the variable-remap environment.

Parameters:

  • var – The borrowed variable identity to bind.

  • mapped_value – The borrowed replacement value.

Returns:

Successful completion or an Error.

Protected Types

using VTable = ObjectFunctor<UnchangedOr<ffi::Any>(const ffi::Object*, ObjectMutator*, InplaceMode)>#

Exact native dispatch table with owning replacement results.

Protected Functions

inline explicit ObjectMutator(const VTable *vtable)#

Construct a mutator with a finalized native dispatch table.

Parameters:

vtable – The immutable table, which must outlive this mutator.

Protected Static Functions

static inline void InitVTable(VTable *vtable)#

Initialize the base registrations in a fresh mutable table.

Parameters:

vtable – The table to initialize before adding derived registrations.

template<typename Self, typename Node>
static inline void SetDispatch(VTable *vtable)#

Register an exact node type in a fresh table initialized by its parent. Derived node types require separate registrations.

Template Parameters:

  • Self – The mutator implementing the hook.

  • Node – The exact node type handled by the hook.

Parameters:

vtable – The mutable table to receive the registration.