Skip to content

[Feat][Rust] Add native structural_map and structural_mutate - #704

Open
tlopex wants to merge 4 commits into
apache:mainfrom
tlopex:feat/rust-structural-map
Open

[Feat][Rust] Add native structural_map and structural_mutate#704
tlopex wants to merge 4 commits into
apache:mainfrom
tlopex:feat/rust-structural-map

Conversation

@tlopex

@tlopex tlopex commented Aug 7, 2026

Copy link
Copy Markdown
Member

This PR adds Rust-native structural transformation support as a counterpart to the structural mapping APIs proposed in #649, building on the Rust structural_visit and structural_walk infrastructure introduced in #693.

The structural transformation algorithm remains in Rust: traversal order, recursion, typed dispatch, definition-region propagation, memoization, and identity remapping are all controlled by the Rust implementation.

For runtime-owned Map and Dict storage, this PR introduces a narrow, pointer-only C ABI. The runtime performs only storage-specific operations such as iteration, uniqueness checks, shallow copying, and value replacement. Each child value is synchronously returned to Rust for structural recursion and dispatch.

Rust APIs

This PR provides:

  • structural_map with pre-order and post-order callbacks.
  • A low-level StructuralMutator trait for user-controlled recursion.
  • Typed closures, ordered callback tuples, and #[dispatch(map)].
  • Definition-region propagation.
  • DAG and FreeVar identity remapping.
  • Structural error context.
  • Native Array, List, Map, Dict, and reflected-object mutation.
  • Copy-on-write and optional in-place container reuse.
  • Map and Dict keys remain structural anchors and are not mapped.

Ownership and mutation semantics

The root is consumed so Rust ownership and the runtime strong-reference count
determine whether a container may be reused.

  • Uniquely owned Array, List, Map, and Dict objects may be updated in place.
  • Passing a shared root, such as root.clone(), selects copy-on-write behavior.
  • A shared immutable Map is shallow-copied lazily when its first changed value
    is found.
  • A shared mutable Dict is shallow-copied before the first callback, providing
    a stable snapshot if a callback re-enters and mutates an alias of the source
    Dict.
  • If no structural value changes, the original object identity is returned.
  • If an in-place transformation fails after earlier values were replaced,
    completed prefix replacements are retained.
  • Partially produced FFI getter, setter, and Map callback results are released
    on error paths.
  • Rust panics are caught at the C ABI boundary and resumed only after runtime
    RAII cleanup has completed.

Stable Map and Dict runtime boundary

This PR adds two additive C ABI functions:

  • TVMFFIMapIterate
  • TVMFFIMapMutateValues

These functions keep the private MapBaseObj small/dense hash-table layout, iteration links, allocator, and deleter inside the runtime that owns them.

Rust no longer mirrors or reads the private C++ Map/Dict storage layout. TVMFFIAny values cross this boundary only through pointers; no C++ Any or AnyView class is passed or returned by value.

The callbacks are synchronous, serial, run on the calling thread, and are not retained by the runtime. Structural recursion and nested transformation remain in Rust.

No object layout or existing C ABI is changed. The two new C symbols are additive. Because Rust calls these symbols directly, the Rust crate and runtime must come from compatible versions; the previous old-runtime reconstruction fallback is removed.

Runtime-registered mutation hooks

Following the boundary established by the Rust structural-visit implementation in #693, this PR does not invoke runtime-registered __s_mutate__ or __s_maybe_inplace_mutate__ hooks.

A non-container type defining either hook is rejected with an actionable error instead of silently replacing its custom mutation semantics with reflected traversal. Its behavior can be implemented explicitly through the RustStructuralMutator trait.

This PR does not construct or mirror the C++ StructuralMutatorObj ABI. Supporting runtime-registered mutation hooks and allowing those hooks to re-enter a Rust mutator requires a separate interoperability layer and remains
outside this PR's scope.

@tlopex
tlopex marked this pull request as draft August 7, 2026 06:27
@tlopex
tlopex force-pushed the feat/rust-structural-map branch 2 times, most recently from 5065ebf to 3b06bc9 Compare August 10, 2026 18:41
Signed-off-by: tlopex <820958424@qq.com>
@tlopex
tlopex force-pushed the feat/rust-structural-map branch from 3b06bc9 to f6358ad Compare August 10, 2026 19:08
@tlopex
tlopex marked this pull request as ready for review August 11, 2026 21:32
Comment thread rust/tvm-ffi-macros/src/dispatch.rs
Comment thread rust/tvm-ffi/src/extra/structural_mutate.rs Outdated
Comment thread rust/tvm-ffi/src/extra/structural_mutate.rs
Comment thread rust/tvm-ffi/src/extra/structural_mutate.rs Outdated
Comment thread rust/tvm-ffi/src/extra/structural_mutate.rs Outdated
Comment thread rust/tvm-ffi/src/extra/structural_mutate.rs Outdated
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants