docs

Signed-off-by: Robert Kruszewski <github@robertk.io>

Author: robert3005

vortex-array/src/matcher.rs

@@ -8,12 +8,36 @@ use crate::array::ParentRef;
 pub trait Matcher {
     type Match<'a>;
 
-    /// Check if the given array matches this matcher type
+    /// Check if the given array matches this matcher type.
+    ///
+    /// # Deprecated
+    ///
+    /// Prefer [`Matcher::matches_parent`]. This method only sees a heap-allocated
+    /// [`ArrayRef`]; stack-allocated parents constructed by [`ArrayParts::optimize`]
+    /// flow through `matches_parent` instead.
+    ///
+    /// Existing implementations can stay; new matchers should override
+    /// [`Matcher::matches_parent`] (and [`Matcher::try_match_parent`]) directly so they
+    /// participate in the stack-backed `reduce_parent` dispatch.
+    ///
+    /// [`ArrayParts::optimize`]: crate::array::ArrayParts::optimize
     fn matches(array: &ArrayRef) -> bool {
         Self::try_match(array).is_some()
     }
 
     /// Try to match the given array, returning the matched view type if successful.
+    ///
+    /// # Deprecated
+    ///
+    /// Prefer [`Matcher::try_match_parent`]. This method only sees a heap-allocated
+    /// [`ArrayRef`]; stack-allocated parents constructed by [`ArrayParts::optimize`]
+    /// flow through `try_match_parent` instead.
+    ///
+    /// Existing implementations can stay; new matchers should override
+    /// [`Matcher::try_match_parent`] directly so they participate in the stack-backed
+    /// `reduce_parent` dispatch.
+    ///
+    /// [`ArrayParts::optimize`]: crate::array::ArrayParts::optimize
     fn try_match<'a>(array: &'a ArrayRef) -> Option<Self::Match<'a>>;
 
     /// Try to match a [`ParentRef`].

vortex-array/src/optimizer/rules.rs

@@ -49,6 +49,16 @@ pub trait ArrayReduceRule<V: VTable>: Debug + Send + Sync + 'static {
 /// The child sees the parent's type via the associated `Parent` [`Matcher`] and can return
 /// a replacement for the parent. This enables optimizations like pushing operations through
 /// compression layers (e.g., pushing a scalar function into dictionary values).
+///
+/// # Migration to `ParentRef`
+///
+/// New rules should override [`ArrayParentReduceRule::reduce_parent_ref`] directly so
+/// they participate in the stack-backed dispatch driven by
+/// [`ArrayParts::optimize`](crate::array::ArrayParts::optimize). The default
+/// `reduce_parent_ref` falls through to [`reduce_parent`](Self::reduce_parent) via
+/// [`Matcher::try_match_parent`], which only matches heap-allocated parents — so
+/// rules that only override `reduce_parent` will still fire on heap-backed parents
+/// but will miss the stack-backed fast path.
 pub trait ArrayParentReduceRule<V: VTable>: Debug + Send + Sync + 'static {
     /// The parent array type this rule matches against.
     type Parent: Matcher;
@@ -59,6 +69,19 @@ pub trait ArrayParentReduceRule<V: VTable>: Debug + Send + Sync + 'static {
     /// - `Ok(Some(new_array))` if the rule applied successfully
     /// - `Ok(None)` if the rule doesn't apply
     /// - `Err(e)` if an error occurred
+    ///
+    /// # Deprecated
+    ///
+    /// Prefer overriding [`ArrayParentReduceRule::reduce_parent_ref`]. This method
+    /// only sees the parent through [`Matcher::Match`], which for the blanket
+    /// `impl<V: VTable> Matcher for V` is an [`ArrayView`] holding an `&ArrayRef` —
+    /// in other words it only fires when the parent is heap-allocated. Rules that
+    /// override `reduce_parent_ref` instead can rewrite stack-allocated parents
+    /// constructed by [`ArrayParts::optimize`](crate::array::ArrayParts::optimize)
+    /// without forcing an `Arc<ArrayInner<V>>` allocation.
+    ///
+    /// Existing implementations can stay; the default `reduce_parent_ref` continues
+    /// to delegate here for heap-backed parents.
     fn reduce_parent(
         &self,
         array: ArrayView<'_, V>,