This is an automated email from the ASF dual-hosted git repository.
tlopex pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/tvm-ffi.git
The following commit(s) were added to refs/heads/main by this push:
new c385ece0 [REFACTOR][Rust] Rename visit policies to context policies
(#799)
c385ece0 is described below
commit c385ece01555c32cf4975a4e818a434d8a22f173
Author: Shushi Hong <[email protected]>
AuthorDate: Thu Sep 17 18:26:00 2026 -0400
[REFACTOR][Rust] Rename visit policies to context policies (#799)
Follow up on #794 while preserving the existing public names as aliases.
---
docs/guides/rust_lang_guide.md | 6 ++---
rust/tvm-ffi/src/extra/structural_visit.rs | 13 +++++++----
rust/tvm-ffi/src/extra/structural_visit/policy.rs | 24 +++++++++----------
rust/tvm-ffi/src/lib.rs | 8 +++----
rust/tvm-ffi/tests/test_structural_visit.rs | 28 +++++++++++------------
5 files changed, 42 insertions(+), 37 deletions(-)
diff --git a/docs/guides/rust_lang_guide.md b/docs/guides/rust_lang_guide.md
index e308d685..6da519a3 100644
--- a/docs/guides/rust_lang_guide.md
+++ b/docs/guides/rust_lang_guide.md
@@ -366,9 +366,9 @@ Callbacks are `Fn`; mutable data belongs in the visitor
state. A catch-all
callback must call `visit_children()` explicitly, and interrupt values must be
returned explicitly because `?` only propagates errors.
-`VisitCallbacks::with_policy` and `WalkWithPolicy` customize default recursion
-with reusable `VisitPolicy<State>` policies. See the `VisitPolicy` API
-documentation for policy composition and state access.
+`VisitCallbacks::with_policy` and `WalkWithPolicy` use `ContextPolicy<State>`
+to manage context around default recursion. See the `ContextPolicy` API
+documentation for composition and shared state access.
For a named implementation, `#[dispatch(visit)]` generates
`StructuralVisitor` from `visit_*` methods. Matching handlers own recursion;
diff --git a/rust/tvm-ffi/src/extra/structural_visit.rs
b/rust/tvm-ffi/src/extra/structural_visit.rs
index 9031de5f..5cea6591 100644
--- a/rust/tvm-ffi/src/extra/structural_visit.rs
+++ b/rust/tvm-ffi/src/extra/structural_visit.rs
@@ -223,7 +223,12 @@ impl From<Error> for NativeHalt {
type NativeResult = std::result::Result<(), NativeHalt>;
mod policy;
-pub use policy::{DefaultVisitPolicy, VisitPolicy, WalkWithPolicy};
+pub use policy::{ContextPolicy, DefaultContextPolicy, WalkWithPolicy};
+
+/// Compatibility name for [`ContextPolicy`].
+pub use policy::ContextPolicy as VisitPolicy;
+/// Compatibility name for [`DefaultContextPolicy`].
+pub use policy::DefaultContextPolicy as DefaultVisitPolicy;
/// State and recursive operations available to a visit callback.
///
@@ -510,7 +515,7 @@ macro_rules! impl_visit_chain_link {
impl_callback_chain_tuple_arities!(impl_visit_chain_link);
/// A reusable callback visitor with shared user state.
-pub struct VisitCallbacks<State, Link, Marker, Policy = DefaultVisitPolicy> {
+pub struct VisitCallbacks<State, Link, Marker, Policy = DefaultContextPolicy> {
policy: Option<Rc<Policy>>,
state: State,
callbacks: Rc<Link>,
@@ -535,7 +540,7 @@ where
impl<State, Link, Marker, Policy> VisitCallbacks<State, Link, Marker, Policy> {
/// Set the default-recursion policy while retaining the callbacks and
state.
/// A matched callback enters the policy only when it calls
`visit_children()`.
- pub fn with_policy<P: VisitPolicy<State>>(
+ pub fn with_policy<P: ContextPolicy<State>>(
self,
policy: P,
) -> VisitCallbacks<State, Link, Marker, P> {
@@ -1089,7 +1094,7 @@ where
impl<State, Link, Marker, Policy> StructuralVisitor for VisitCallbacks<State,
Link, Marker, Policy>
where
Link: VisitChainLink<State, Marker>,
- Policy: VisitPolicy<State>,
+ Policy: ContextPolicy<State>,
{
fn visit(
&mut self,
diff --git a/rust/tvm-ffi/src/extra/structural_visit/policy.rs
b/rust/tvm-ffi/src/extra/structural_visit/policy.rs
index 9b6b3d1c..502f0df4 100644
--- a/rust/tvm-ffi/src/extra/structural_visit/policy.rs
+++ b/rust/tvm-ffi/src/extra/structural_visit/policy.rs
@@ -21,14 +21,14 @@
use super::*;
-/// A reusable default-recursion policy sharing state with traversal callbacks.
+/// A reusable policy for managing context around default visit and walk
recursion.
///
/// `visit_children()` on this policy's context continues with the next policy
/// (or the built-in hooks and reflected fields). `visit()` re-enters the full
/// callback engine for a child. A tuple `(outer, inner)` composes two
policies;
/// tuples may nest. Policies are shared during recursive calls, so mutable
data
-/// belongs in the context's state.
-pub trait VisitPolicy<State> {
+/// belongs in the context's state. Save and restore scoped state around
descent.
+pub trait ContextPolicy<State> {
/// Customize default descent for the current value.
///
/// Return interrupts explicitly, and restore any scoped state before
@@ -43,9 +43,9 @@ pub trait VisitPolicy<State> {
}
/// Default descent through registered hooks or reflected structural fields.
-pub struct DefaultVisitPolicy;
+pub struct DefaultContextPolicy;
-impl<State> VisitPolicy<State> for DefaultVisitPolicy {
+impl<State> ContextPolicy<State> for DefaultContextPolicy {
fn default_visit(
&self,
_value: &StructuralView,
@@ -55,7 +55,7 @@ impl<State> VisitPolicy<State> for DefaultVisitPolicy {
}
}
-impl<State, Outer: VisitPolicy<State>, Inner: VisitPolicy<State>>
VisitPolicy<State>
+impl<State, Outer: ContextPolicy<State>, Inner: ContextPolicy<State>>
ContextPolicy<State>
for (Outer, Inner)
{
fn default_visit(
@@ -78,7 +78,7 @@ impl<State, Outer: VisitPolicy<State>, Inner:
VisitPolicy<State>> VisitPolicy<St
pub(super) fn visit_with_policy<State>(
driver: &mut dyn VisitContextDriver<State>,
- policy: &impl VisitPolicy<State>,
+ policy: &impl ContextPolicy<State>,
value: &StructuralView,
def_region_kind: DefRegionKind,
) -> Result<Option<VisitInterrupt>> {
@@ -98,7 +98,7 @@ struct NextPolicy<'a, State, Policy> {
policy: &'a Policy,
}
-impl<State, Policy: VisitPolicy<State>> VisitContextDriver<State>
+impl<State, Policy: ContextPolicy<State>> VisitContextDriver<State>
for NextPolicy<'_, State, Policy>
{
fn state(&self) -> &State {
@@ -160,7 +160,7 @@ pub struct WalkWithPolicy<Walker, Policy> {
policy: Rc<Policy>,
}
-impl<Walker: WalkDispatch, Policy: VisitPolicy<Walker>> WalkWithPolicy<Walker,
Policy> {
+impl<Walker: WalkDispatch, Policy: ContextPolicy<Walker>>
WalkWithPolicy<Walker, Policy> {
/// Combine a dispatcher and a default-recursion policy.
pub fn new(walker: Walker, policy: Policy) -> Self {
Self {
@@ -204,7 +204,7 @@ impl<Walker: WalkDispatch, Policy: VisitPolicy<Walker>>
WalkWithPolicy<Walker, P
#[doc(hidden)]
pub enum ByPolicyWalk {}
-impl<Walker: WalkDispatch, Policy: VisitPolicy<Walker>>
IntoWalker<ByPolicyWalk>
+impl<Walker: WalkDispatch, Policy: ContextPolicy<Walker>>
IntoWalker<ByPolicyWalk>
for WalkWithPolicy<Walker, Policy>
{
type Walker = Self;
@@ -213,7 +213,7 @@ impl<Walker: WalkDispatch, Policy: VisitPolicy<Walker>>
IntoWalker<ByPolicyWalk>
}
}
-impl<Walker: WalkDispatch, Policy: VisitPolicy<Walker>> NativeVisit
+impl<Walker: WalkDispatch, Policy: ContextPolicy<Walker>> NativeVisit
for WalkWithPolicy<Walker, Policy>
{
const CUSTOM_DESCENT: bool = true;
@@ -248,7 +248,7 @@ struct WalkDescent<'a, Walker, Policy, const PRE_ORDER:
bool> {
visitor: &'a mut WalkWithPolicy<Walker, Policy>,
}
-impl<Walker: WalkDispatch, Policy: VisitPolicy<Walker>, const PRE_ORDER: bool>
+impl<Walker: WalkDispatch, Policy: ContextPolicy<Walker>, const PRE_ORDER:
bool>
VisitContextDriver<Walker> for WalkDescent<'_, Walker, Policy, PRE_ORDER>
{
fn state(&self) -> &Walker {
diff --git a/rust/tvm-ffi/src/lib.rs b/rust/tvm-ffi/src/lib.rs
index 4bb5672c..f6ddd640 100644
--- a/rust/tvm-ffi/src/lib.rs
+++ b/rust/tvm-ffi/src/lib.rs
@@ -54,10 +54,10 @@ pub use crate::extra::structural_mutate::{
MutateContext, MutateDispatch, MutateValue, Mutator, StructuralMutator,
StructuralVarRemap,
};
pub use crate::extra::structural_visit::{
- structural_visit, structural_walk, DefRegionKind, DefaultVisitPolicy,
IntoVisitor,
- IntoWalkResult, IntoWalker, StructuralVisitor, VisitCallbacks,
VisitChainLink, VisitContext,
- VisitInterrupt, VisitPolicy, VisitValue, WalkChainLink, WalkDispatch,
WalkOrder, WalkResult,
- WalkWithPolicy,
+ structural_visit, structural_walk, ContextPolicy, DefRegionKind,
DefaultContextPolicy,
+ DefaultVisitPolicy, IntoVisitor, IntoWalkResult, IntoWalker,
StructuralVisitor, VisitCallbacks,
+ VisitChainLink, VisitContext, VisitInterrupt, VisitPolicy, VisitValue,
WalkChainLink,
+ WalkDispatch, WalkOrder, WalkResult, WalkWithPolicy,
};
pub use crate::extra::unchanged::{Unchanged, UnchangedOr};
pub use crate::extra::StructuralView;
diff --git a/rust/tvm-ffi/tests/test_structural_visit.rs
b/rust/tvm-ffi/tests/test_structural_visit.rs
index e1b42cba..2858844f 100644
--- a/rust/tvm-ffi/tests/test_structural_visit.rs
+++ b/rust/tvm-ffi/tests/test_structural_visit.rs
@@ -20,10 +20,10 @@
use std::cell::{Cell, RefCell};
use tvm_ffi::object::ObjectRef;
use tvm_ffi::{
- dispatch, get_type_attr, structural_visit, structural_walk, Any, Array,
DLDataType,
- DLDataTypeCode, DefRegionKind, Error, FieldGetter, Function, Map, Object,
ObjectRefCore,
- Result, String as FfiString, StructuralVisitor, TypeIndex, VisitCallbacks,
VisitContext,
- VisitInterrupt, VisitPolicy, VisitValue, WalkOrder, WalkResult,
WalkWithPolicy, RUNTIME_ERROR,
+ dispatch, get_type_attr, structural_visit, structural_walk, Any, Array,
ContextPolicy,
+ DLDataType, DLDataTypeCode, DefRegionKind, Error, FieldGetter, Function,
Map, Object,
+ ObjectRefCore, Result, String as FfiString, StructuralVisitor, TypeIndex,
VisitCallbacks,
+ VisitContext, VisitInterrupt, VisitValue, WalkOrder, WalkResult,
WalkWithPolicy, RUNTIME_ERROR,
};
fn runtime_error(message: &str) -> Error {
@@ -49,7 +49,7 @@ fn
composed_policies_share_array_scope_with_visit_and_walk_callbacks() {
// It does not know what the callbacks will do with the current depth.
struct ArrayScope;
- impl VisitPolicy<CollectIntegers> for ArrayScope {
+ impl ContextPolicy<CollectIntegers> for ArrayScope {
fn default_visit(
&self,
value: &VisitValue,
@@ -74,7 +74,7 @@ fn
composed_policies_share_array_scope_with_visit_and_walk_callbacks() {
// reaches the built-in Array hook, whose children re-enter the full
engine.
struct RecordDescent;
- impl VisitPolicy<CollectIntegers> for RecordDescent {
+ impl ContextPolicy<CollectIntegers> for RecordDescent {
fn default_visit(
&self,
_value: &VisitValue,
@@ -166,7 +166,7 @@ fn
policy_continuation_scopes_regions_and_restores_after_halts() {
}
}
struct Scope(DefRegionKind, i64);
- impl VisitPolicy<Probe> for Scope {
+ impl ContextPolicy<Probe> for Scope {
fn default_visit(
&self,
value: &VisitValue,
@@ -276,7 +276,7 @@ fn
policy_continuation_retargets_without_dispatching_the_container() {
}
struct Redirect;
- impl VisitPolicy<Probe> for Redirect {
+ impl ContextPolicy<Probe> for Redirect {
fn default_visit(
&self,
value: &VisitValue,
@@ -303,7 +303,7 @@ fn
policy_continuation_retargets_without_dispatching_the_container() {
}
struct Observe;
- impl VisitPolicy<Probe> for Observe {
+ impl ContextPolicy<Probe> for Observe {
fn default_visit(
&self,
value: &VisitValue,
@@ -426,7 +426,7 @@ fn
policy_halts_skip_remaining_policies_and_restore_outer_state() {
}
}
struct Scope;
- impl VisitPolicy<Probe> for Scope {
+ impl ContextPolicy<Probe> for Scope {
fn default_visit(
&self,
value: &VisitValue,
@@ -442,7 +442,7 @@ fn
policy_halts_skip_remaining_policies_and_restore_outer_state() {
}
}
struct Stop(bool);
- impl VisitPolicy<Probe> for Stop {
+ impl ContextPolicy<Probe> for Stop {
fn default_visit(
&self,
_: &VisitValue,
@@ -459,7 +459,7 @@ fn
policy_halts_skip_remaining_policies_and_restore_outer_state() {
}
}
struct Unreachable;
- impl VisitPolicy<Probe> for Unreachable {
+ impl ContextPolicy<Probe> for Unreachable {
fn default_visit(
&self,
_: &VisitValue,
@@ -508,7 +508,7 @@ fn
policy_halts_skip_remaining_policies_and_restore_outer_state() {
#[test]
fn policy_regions_compose_with_field_flags_and_function_hooks() {
struct SetRootRegion(i32, DefRegionKind);
- impl VisitPolicy<PolicyRegionTrace> for SetRootRegion {
+ impl ContextPolicy<PolicyRegionTrace> for SetRootRegion {
fn default_visit(
&self,
value: &VisitValue,
@@ -573,7 +573,7 @@ fn
policy_regions_compose_with_field_flags_and_function_hooks() {
fn walk_policy_preserves_reflected_pattern_before_default_descent() {
let root = visit_region_graph(false);
struct Reenter(DefRegionKind);
- impl VisitPolicy<PolicyRegionTrace> for Reenter {
+ impl ContextPolicy<PolicyRegionTrace> for Reenter {
fn default_visit(
&self,
value: &VisitValue,
