Class StructuralVisitorObj

Class StructuralVisitorObj#

Inheritance Relationships#

Base Type#

Class Documentation#

class StructuralVisitorObj : public tvm::ffi::Object#

Object node of a structural visitor.

A structural visitor is an active traversal context. It carries the dispatch table used to visit each object and the current def-region state used by structural equality/hash semantics. The visitor is ref-counted so it can cross FFI boundaries, but one underlying visitor object should not be shared by overlapping top-level traversals.

Public Types

using VisitorObjType = StructuralVisitorObj#

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

using StateTupleType = std::tuple<>#

State references made available to callback-aware visitor layers.

Public Functions

inline Optional<VisitInterrupt> Visit(AnyView value)#

Visit a value, dispatching through this visitor’s vtable.

Parameters:

value – The value to visit.

Returns:

std::nullopt to continue traversal, or a VisitInterrupt to halt the entire visit.

inline Expected<Optional<VisitInterrupt>> VisitExpected(AnyView value) noexcept#

Visit a value, propagating error through expected return.

Parameters:

value – The value to visit.

Returns:

Expected interrupt state. An error means traversal failed.

inline TVMFFIDefRegionKind def_region_kind() const#

Return the current def-region context.

Note

A custom visit 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)#

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 visiting.

Returns:

The value returned by callback.

inline Expected<Optional<VisitInterrupt>> DefaultVisitExpected(AnyView value) noexcept#

Visit using the structural visit behavior registered by kStructuralVisit for each type, or reflected structural fields when no custom behavior is registered.

Note

Dispatches to the value type’s registered __s_visit__ hook, falling back to reflected fields only when no hook is registered. Call it on a child, or on a matched value from a StructuralVisit callback to bypass callback dispatch for that value. Called on the value whose own hook is running, it re-enters that hook &#8212; there is no way to request the reflected path from inside a hook.

Parameters:

value – The value to visit.

Returns:

Expected interrupt state. An error means traversal failed.

Protected Functions

inline StateTupleType StateTuple() const noexcept#

Return the state references maintained by this visitor layer.

inline explicit StructuralVisitorObj(const StructuralVisitorVTable *vtable)#

Construct a structural visitor from an immutable dispatch vtable.

Parameters:

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

Protected Attributes

const StructuralVisitorVTable *vtable_ = nullptr#

Required ABI dispatch table. StructuralVisitorVTable It must never be null on a constructed visitor.

TVMFFIDefRegionKind def_region_mode_ = kTVMFFIDefRegionKindNone#

Current def-region context for structural equality/hash semantics.

This is shared mutable traversal state. Be careful when mutating it through multiple references to the same visitor object. Use WithDefRegionKind to scope temporary changes.