Skip to main content

structural_walk

Function structural_walk 

Source
pub fn structural_walk<'input, R, M, H, D, O>(
    root: R,
    walker: H,
    order: WalkOrder,
) -> Result<Option<VisitInterrupt>>
where for<'v> H: IntoDispatcher<(AnyView<'v>, DefRegionKind), Option<Result<WalkResult>>, M, Target = D, Output = O>, for<'s, 'v> &'s mut D: Dispatcher<(AnyView<'v>, DefRegionKind), Option<Result<WalkResult>>>, R: Into<AnyView<'input>>, O: BorrowMut<D>,
Expand description

Walk root with an observer, calling it on every reachable value in order.

walker is anything implementing IntoDispatcher: a &mut reference to a stateful Dispatcher walker (declared with #[dispatch]), a bare closure in any crate::IntoDispatcher callback shape (catch-all AnyView<'_>, typed, or node, with an optional trailing DefRegionKind), or a tuple of such callbacks tried in order until one matches. Callback views cannot escape their invocation; retain an Any explicitly when a value must outlive the callback:

ⓘ
use tvm_ffi::{structural_walk, AnyView, WalkOrder, WalkResult};
let mut retained: Option<AnyView<'static>> = None;
structural_walk(&1_i64, |value: AnyView<'_>| {
    retained = Some(value);
    WalkResult::Advance
}, WalkOrder::PreOrder).unwrap();

The walker owns recursion: the handler runs once per value, before or after the value’s children according to order, and steers traversal through the returned WalkResult. Walk accepts its existing dispatcher borrows, closure observers and callback tuples; each adapter runs through the same borrowed traversal engine.

Callbacks must report failures through Result and must not panic: a panic reaching the non-unwinding native callback boundary aborts the process.

A callback must not modify an ffi.List or ffi.Dict that holds the value it receives or one of that value’s ancestors: the traversal borrows their cells while the callback runs.

§Arguments

  • root - Value borrowed for traversal, convertible into an AnyView.
  • walker - Mutable dispatcher, closure, or first-match callback tuple implementing IntoDispatcher. Each callback observes a value and returns a result convertible through IntoWalkResult to control traversal.
  • order - WalkOrder::PreOrder observes each value before its children; WalkOrder::PostOrder observes it after its children. Skipping children with WalkResult::Skip only affects pre-order traversal.

§Examples

Collect integer leaves with a typed closure:

use tvm_ffi::{structural_walk, Array, WalkOrder, WalkResult};

let root = Array::from_vec(vec![1_i64, 2, 3]);
let mut integers = Vec::new();
structural_walk(&root, |value: i64| {
    integers.push(value);
    WalkResult::Advance
}, WalkOrder::PreOrder)?;
assert_eq!(integers, vec![1, 2, 3]);