vortex_array/array/
erased.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::any::type_name;
5use std::fmt::Debug;
6use std::fmt::Formatter;
7use std::hash::Hash;
8use std::hash::Hasher;
9use std::ops::Range;
10use std::sync::Arc;
11
12use vortex_buffer::ByteBuffer;
13use vortex_error::VortexExpect;
14use vortex_error::VortexResult;
15use vortex_error::vortex_ensure;
16use vortex_error::vortex_err;
17use vortex_error::vortex_panic;
18use vortex_mask::Mask;
19
20use crate::AnyCanonical;
21use crate::Array;
22use crate::ArrayEq;
23use crate::ArrayHash;
24use crate::ArrayView;
25use crate::Canonical;
26use crate::ExecutionCtx;
27use crate::ExecutionResult;
28use crate::IntoArray;
29use crate::VTable;
30use crate::VortexSessionExecute;
31use crate::aggregate_fn::fns::sum::sum;
32use crate::array::ArrayData;
33use crate::array::ArrayId;
34use crate::array::ArrayInner;
35use crate::array::ArraySlots;
36use crate::array::DynArrayData;
37use crate::arrays::Bool;
38use crate::arrays::Constant;
39use crate::arrays::DictArray;
40use crate::arrays::FilterArray;
41use crate::arrays::Null;
42use crate::arrays::Primitive;
43use crate::arrays::SliceArray;
44use crate::arrays::VarBin;
45use crate::arrays::VarBinView;
46use crate::buffer::BufferHandle;
47use crate::builders::ArrayBuilder;
48use crate::dtype::DType;
49use crate::expr::stats::Precision;
50use crate::expr::stats::Stat;
51use crate::expr::stats::StatsProviderExt;
52use crate::legacy_session;
53use crate::matcher::Matcher;
54use crate::optimizer::ArrayOptimizer;
55use crate::scalar::Scalar;
56use crate::scalar::ScalarValue;
57use crate::stats::StatsSetRef;
58use crate::validity::Validity;
59
60/// A depth-first pre-order iterator over an Array.
61pub struct DepthFirstArrayIterator {
62    stack: Vec<ArrayRef>,
63}
64
65impl Iterator for DepthFirstArrayIterator {
66    type Item = ArrayRef;
67
68    fn next(&mut self) -> Option<Self::Item> {
69        let next = self.stack.pop()?;
70        for child in next.children().into_iter().rev() {
71            self.stack.push(child);
72        }
73        Some(next)
74    }
75}
76
77/// A reference-counted pointer to a type-erased array.
78///
79/// Wraps `Arc<ArrayInner<dyn DynArrayData>>` — a single 16-byte fat pointer.
80/// Metadata (`len`, `dtype`, `encoding_id`) lives in `ArrayInner::meta` and is
81/// accessed as a normal struct field read — no vtable dispatch, no extra allocation.
82#[derive(Clone)]
83pub struct ArrayRef(Arc<ArrayInner<dyn DynArrayData>>);
84
85impl ArrayRef {
86    /// Create from an `Arc<ArrayInner<dyn DynArrayData>>`.
87    pub(crate) fn from_inner<D: DynArrayData>(inner: Arc<ArrayInner<D>>) -> Self {
88        Self(inner)
89    }
90
91    /// Returns a reference to the `dyn DynArrayData` inside the inner.
92    #[inline(always)]
93    pub(crate) fn dyn_array(&self) -> &dyn DynArrayData {
94        &self.0.data
95    }
96
97    /// Returns a mutable reference to the inner if this is the sole owner.
98    #[inline(always)]
99    pub(crate) fn inner_mut(&mut self) -> Option<&mut ArrayInner<dyn DynArrayData>> {
100        Arc::get_mut(&mut self.0)
101    }
102
103    /// Returns the Arc::as_ptr().addr() of the underlying array.
104    /// This function is used in a couple of places, and we should migrate them to using array_eq.
105    #[doc(hidden)]
106    pub fn addr(&self) -> usize {
107        Arc::as_ptr(&self.0).addr()
108    }
109
110    /// Downcast the inner to a concrete `ArrayInner<ArrayData<V>>`.
111    ///
112    /// Uses the same raw-pointer technique as `Arc::downcast`.
113    #[allow(dead_code)]
114    pub(crate) fn downcast_inner<V: VTable>(self) -> Result<Arc<ArrayInner<ArrayData<V>>>, Self> {
115        // TODO(joe): can we use encoding id here?
116        if self.0.data.as_any().is::<ArrayData<V>>() {
117            Ok(unsafe { self.downcast_inner_unchecked() })
118        } else {
119            Err(self)
120        }
121    }
122
123    /// Downcast without a runtime type check.
124    ///
125    /// # Safety
126    /// The caller must guarantee the concrete type behind `dyn DynArrayData` is `ArrayData<V>`.
127    #[inline(always)]
128    pub(crate) unsafe fn downcast_inner_unchecked<V: VTable>(
129        self,
130    ) -> Arc<ArrayInner<ArrayData<V>>> {
131        debug_assert!(self.0.data.as_any().is::<ArrayData<V>>());
132        // Recover the original concrete Arc. The fat pointer's data pointer is the
133        // same allocation that was originally `Arc<ArrayInner<ArrayData<V>>>` before
134        // unsized coercion to `Arc<ArrayInner<dyn DynArrayData>>`.
135        let raw = Arc::into_raw(self.0);
136        // # Safety all arrays are constructed in this way and type aliased.
137        unsafe { Arc::from_raw(raw.cast::<ArrayInner<ArrayData<V>>>()) }
138    }
139
140    /// Returns true if the two ArrayRefs point to the same allocation.
141    pub fn ptr_eq(this: &ArrayRef, other: &ArrayRef) -> bool {
142        Arc::ptr_eq(&this.0, &other.0)
143    }
144}
145
146impl Debug for ArrayRef {
147    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
148        f.debug_struct("Array")
149            .field("encoding", &self.0.encoding_id)
150            .field("dtype", &self.0.dtype)
151            .field("len", &self.0.len)
152            .field("data", &self.0.data)
153            .finish()
154    }
155}
156
157impl ArrayHash for ArrayRef {
158    fn array_hash<H: Hasher>(&self, state: &mut H, accuracy: crate::EqMode) {
159        self.0.len.hash(state);
160        self.0.dtype.hash(state);
161        self.0.encoding_id.hash(state);
162        self.0.slots.len().hash(state);
163        for slot in &self.0.slots {
164            slot.array_hash(state, accuracy);
165        }
166        self.0
167            .data
168            .dyn_array_hash(state as &mut dyn Hasher, accuracy);
169    }
170}
171
172impl ArrayEq for ArrayRef {
173    fn array_eq(&self, other: &Self, accuracy: crate::EqMode) -> bool {
174        self.0.len == other.0.len
175            && self.0.dtype == other.0.dtype
176            && self.0.encoding_id == other.0.encoding_id
177            && self.0.slots.len() == other.0.slots.len()
178            && self
179                .0
180                .slots
181                .iter()
182                .zip(other.0.slots.iter())
183                .all(|(slot, other_slot)| slot.array_eq(other_slot, accuracy))
184            && self.0.data.dyn_array_eq(other, accuracy)
185    }
186}
187impl ArrayRef {
188    /// Returns the length of the array.
189    #[inline]
190    pub fn len(&self) -> usize {
191        self.0.len
192    }
193
194    /// Returns whether the array is empty (has zero rows).
195    #[inline]
196    pub fn is_empty(&self) -> bool {
197        self.0.len == 0
198    }
199
200    /// Returns the logical Vortex [`DType`] of the array.
201    #[inline]
202    pub fn dtype(&self) -> &DType {
203        &self.0.dtype
204    }
205
206    /// Returns the encoding ID of the array.
207    #[inline]
208    pub fn encoding_id(&self) -> ArrayId {
209        self.0.encoding_id
210    }
211
212    /// Performs a constant-time slice of the array.
213    pub fn slice(&self, range: Range<usize>) -> VortexResult<ArrayRef> {
214        let len = self.len();
215        let start = range.start;
216        let stop = range.end;
217
218        if start == 0 && stop == len {
219            return Ok(self.clone());
220        }
221
222        vortex_ensure!(start <= len, "OutOfBounds: start {start} > length {}", len);
223        vortex_ensure!(stop <= len, "OutOfBounds: stop {stop} > length {}", len);
224
225        vortex_ensure!(start <= stop, "start ({start}) must be <= stop ({stop})");
226
227        if start == stop {
228            return Ok(Canonical::empty(self.dtype()).into_array());
229        }
230
231        let sliced = SliceArray::try_new(self.clone(), range)?
232            .into_array()
233            .optimize()?;
234
235        // Propagate some stats from the original array to the sliced array.
236        if !sliced.is::<Constant>() {
237            self.statistics().with_iter(|iter| {
238                sliced.statistics().inherit(iter.filter(|(stat, value)| {
239                    matches!(
240                        stat,
241                        Stat::IsConstant | Stat::IsSorted | Stat::IsStrictSorted
242                    ) && value
243                        .as_ref()
244                        .as_exact()
245                        .is_some_and(|v| matches!(v, ScalarValue::Bool(true)))
246                }));
247            });
248        }
249
250        Ok(sliced)
251    }
252
253    /// Wraps the array in a [`FilterArray`] such that it is logically filtered by the given mask.
254    pub fn filter(&self, mask: Mask) -> VortexResult<ArrayRef> {
255        FilterArray::try_new(self.clone(), mask)?
256            .into_array()
257            .optimize()
258    }
259
260    /// Wraps the array in a [`DictArray`] such that it is logically taken by the given indices.
261    pub fn take(&self, indices: ArrayRef) -> VortexResult<ArrayRef> {
262        DictArray::try_new(indices, self.clone())?
263            .into_array()
264            .optimize()
265    }
266
267    /// Fetch the scalar at the given index.
268    #[deprecated(
269        note = "Use `execute_scalar` instead, which allows passing an execution context for more \
270        efficient execution when fetching multiple scalars from the same array."
271    )]
272    #[allow(clippy::disallowed_methods)]
273    pub fn scalar_at(&self, index: usize) -> VortexResult<Scalar> {
274        self.execute_scalar(index, &mut legacy_session().create_execution_ctx())
275    }
276
277    /// Execute the array to extract a scalar at the given index.
278    pub fn execute_scalar(&self, index: usize, ctx: &mut ExecutionCtx) -> VortexResult<Scalar> {
279        vortex_ensure!(index < self.len(), OutOfBounds: index, 0, self.len());
280        if self.dtype().is_nullable() && self.is_invalid(index, ctx)? {
281            return Ok(Scalar::null(self.dtype().clone()));
282        }
283        let scalar = self.0.data.execute_scalar(self, index, ctx)?;
284        debug_assert_eq!(self.dtype(), scalar.dtype(), "Scalar dtype mismatch");
285        Ok(scalar)
286    }
287
288    /// Returns whether the item at `index` is valid.
289    pub fn is_valid(&self, index: usize, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
290        vortex_ensure!(index < self.len(), OutOfBounds: index, 0, self.len());
291        match self.validity()? {
292            Validity::NonNullable | Validity::AllValid => Ok(true),
293            Validity::AllInvalid => Ok(false),
294            Validity::Array(a) => a
295                .execute_scalar(index, ctx)?
296                .as_bool()
297                .value()
298                .ok_or_else(|| vortex_err!("validity value at index {} is null", index)),
299        }
300    }
301
302    /// Returns whether the item at `index` is invalid.
303    pub fn is_invalid(&self, index: usize, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
304        Ok(!self.is_valid(index, ctx)?)
305    }
306
307    /// Returns whether all items in the array are valid.
308    pub fn all_valid(&self, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
309        match self.validity()? {
310            Validity::NonNullable | Validity::AllValid => Ok(true),
311            Validity::AllInvalid => Ok(false),
312            Validity::Array(a) => Ok(a.statistics().compute_min::<bool>(ctx).unwrap_or(false)),
313        }
314    }
315
316    /// Returns whether the array is all invalid.
317    pub fn all_invalid(&self, ctx: &mut ExecutionCtx) -> VortexResult<bool> {
318        match self.validity()? {
319            Validity::NonNullable | Validity::AllValid => Ok(false),
320            Validity::AllInvalid => Ok(true),
321            Validity::Array(a) => Ok(!a.statistics().compute_max::<bool>(ctx).unwrap_or(true)),
322        }
323    }
324
325    /// Returns the number of valid elements in the array.
326    pub fn valid_count(&self, ctx: &mut ExecutionCtx) -> VortexResult<usize> {
327        let len = self.len();
328        if let Precision::Exact(invalid_count) = self.statistics().get_as::<usize>(Stat::NullCount)
329        {
330            return Ok(len - invalid_count);
331        }
332
333        let count = match self.validity()? {
334            Validity::NonNullable | Validity::AllValid => len,
335            Validity::AllInvalid => 0,
336            Validity::Array(a) => {
337                let array_sum = sum(&a, ctx)?;
338                array_sum
339                    .as_primitive()
340                    .as_::<usize>()
341                    .ok_or_else(|| vortex_err!("sum of validity array is null"))?
342            }
343        };
344        vortex_ensure!(count <= len, "Valid count exceeds array length");
345
346        self.statistics()
347            .set(Stat::NullCount, Precision::exact(len - count));
348
349        Ok(count)
350    }
351
352    /// Returns the number of invalid elements in the array.
353    pub fn invalid_count(&self, ctx: &mut ExecutionCtx) -> VortexResult<usize> {
354        Ok(self.len() - self.valid_count(ctx)?)
355    }
356
357    /// Returns the [`Validity`] of the array.
358    pub fn validity(&self) -> VortexResult<Validity> {
359        self.0.data.validity(self)
360    }
361
362    /// Returns the canonical representation of the array.
363    #[deprecated(note = "use `array.execute::<Canonical>(ctx)` instead")]
364    #[allow(clippy::disallowed_methods)]
365    pub fn into_canonical(self) -> VortexResult<Canonical> {
366        self.execute(&mut legacy_session().create_execution_ctx())
367    }
368
369    /// Returns the canonical representation of the array.
370    #[deprecated(note = "use `array.execute::<Canonical>(ctx)` instead")]
371    pub fn to_canonical(&self) -> VortexResult<Canonical> {
372        #[expect(deprecated)]
373        let result = self.clone().into_canonical();
374        result
375    }
376
377    /// Writes the array into the canonical builder.
378    pub fn append_to_builder(
379        &self,
380        builder: &mut dyn ArrayBuilder,
381        ctx: &mut ExecutionCtx,
382    ) -> VortexResult<()> {
383        self.0.data.append_to_builder(self, builder, ctx)
384    }
385
386    /// Returns the statistics of the array.
387    pub fn statistics(&self) -> StatsSetRef<'_> {
388        self.0.stats.to_ref(self)
389    }
390
391    /// Does the array match the given matcher.
392    #[inline]
393    pub fn is<M: Matcher>(&self) -> bool {
394        M::matches(self)
395    }
396
397    /// Returns the array downcast by the given matcher.
398    #[inline]
399    pub fn as_<M: Matcher>(&self) -> M::Match<'_> {
400        self.as_opt::<M>().vortex_expect("Failed to downcast")
401    }
402
403    /// Returns the array downcast by the given matcher.
404    #[inline]
405    pub fn as_opt<M: Matcher>(&self) -> Option<M::Match<'_>> {
406        M::try_match(self)
407    }
408
409    /// Returns the array downcast to the given `Array<V>` as an owned typed handle.
410    pub fn try_downcast<V: VTable>(self) -> Result<Array<V>, ArrayRef> {
411        Array::<V>::try_from_array_ref(self)
412    }
413
414    /// Returns the array downcast to the given `Array<V>` as an owned typed handle.
415    ///
416    /// # Panics
417    ///
418    /// Panics if the array is not of the given type.
419    pub fn downcast<V: VTable>(self) -> Array<V> {
420        Self::try_downcast(self)
421            .unwrap_or_else(|_| vortex_panic!("Failed to downcast to {}", type_name::<V>()))
422    }
423
424    /// Returns a reference to the typed `ArrayData<V>` if this array matches the given vtable type.
425    pub fn as_typed<V: VTable>(&self) -> Option<ArrayView<'_, V>> {
426        let inner = self.0.data.as_any().downcast_ref::<ArrayData<V>>()?;
427        Some(unsafe { ArrayView::new_unchecked(self, &inner.data) })
428    }
429
430    /// Returns the constant scalar if this is a constant array.
431    pub fn as_constant(&self) -> Option<Scalar> {
432        self.as_opt::<Constant>().map(|a| a.scalar().clone())
433    }
434
435    /// Total size of the array in bytes, including all children and buffers.
436    pub fn nbytes(&self) -> u64 {
437        let mut nbytes = 0;
438        for array in self.depth_first_traversal() {
439            for buffer in array.buffers() {
440                nbytes += buffer.len() as u64;
441            }
442        }
443        nbytes
444    }
445
446    /// Returns whether this array is an arrow encoding.
447    pub fn is_arrow(&self) -> bool {
448        self.is::<Null>()
449            || self.is::<Bool>()
450            || self.is::<Primitive>()
451            || self.is::<VarBin>()
452            || self.is::<VarBinView>()
453    }
454
455    /// Whether the array is of a canonical encoding.
456    pub fn is_canonical(&self) -> bool {
457        self.is::<AnyCanonical>()
458    }
459
460    /// Returns a new array with the slot at `slot_idx` replaced by `replacement`.
461    ///
462    /// This is only valid for physical rewrites: the replacement must have the same logical
463    /// `DType` and `len` as the existing slot.
464    ///
465    /// # Safety
466    ///
467    /// If this returns `Ok`, the caller must guarantee that the replacement slot represents the
468    /// same logical values as the original slot. Only the physical representation may change.
469    /// Existing parent statistics are preserved and must remain valid.
470    ///
471    /// Takes ownership to allow in-place mutation when the refcount is 1.
472    pub unsafe fn with_slot(
473        self,
474        slot_idx: usize,
475        replacement: ArrayRef,
476    ) -> VortexResult<ArrayRef> {
477        let mut slots: ArraySlots = self.slots().iter().cloned().collect();
478        let nslots = slots.len();
479        vortex_ensure!(
480            slot_idx < nslots,
481            "slot index {} out of bounds for array with {} slots",
482            slot_idx,
483            nslots
484        );
485        let existing = slots[slot_idx]
486            .as_ref()
487            .vortex_expect("with_slot cannot replace an absent slot");
488        vortex_ensure!(
489            existing.dtype() == replacement.dtype(),
490            "slot {} dtype changed from {} to {} during physical rewrite",
491            slot_idx,
492            existing.dtype(),
493            replacement.dtype()
494        );
495        vortex_ensure!(
496            existing.len() == replacement.len(),
497            "slot {} len changed from {} to {} during physical rewrite",
498            slot_idx,
499            existing.len(),
500            replacement.len()
501        );
502        slots[slot_idx] = Some(replacement);
503        // SAFETY: upheld by the caller of this unsafe API.
504        unsafe { self.with_slots(slots) }
505    }
506
507    /// Take a slot for executor-owned physical rewrites.
508    ///
509    /// On return the produced parent has the taken slot set to `None`
510    /// callers must put the slot back (typically via [`Self::put_slot_unchecked`]) before the parent is
511    /// returned from the execution loop.
512    ///
513    /// When the `Arc` was shared this allocates a fresh parent.
514    ///
515    /// # Safety
516    /// The caller must put back a slot with the same logical dtype and length before exposing the
517    /// parent array, and must only use this for physical rewrites.
518    pub(crate) unsafe fn take_slot_unchecked(
519        mut self,
520        slot_idx: usize,
521    ) -> VortexResult<(ArrayRef, ArrayRef)> {
522        if let Some(inner) = Arc::get_mut(&mut self.0) {
523            let child = inner.slots[slot_idx]
524                .take()
525                .vortex_expect("take_slot_unchecked cannot take an absent slot");
526            return Ok((self, child));
527        }
528
529        // Arc is shared: clone the child out and build a fresh parent with slot_idx = None,
530        // bypassing encoding-level validation so the absent slot does not panic `V::validate`.
531        let child = self.slots()[slot_idx]
532            .as_ref()
533            .vortex_expect("take_slot_unchecked cannot take an absent slot")
534            .clone();
535
536        let mut new_slots: ArraySlots = self.slots().iter().cloned().collect();
537        new_slots[slot_idx] = None;
538
539        // SAFETY: ensured by the caller — the None slot is either put back or driven to completion
540        // via the builder path before the parent escapes the executor.
541        let new_parent = unsafe { self.0.data.with_slots_unchecked(&self, new_slots) };
542        Ok((new_parent, child))
543    }
544
545    /// Puts an array into `slot_idx` by either, cloning the inner array if the Arc is not exclusive
546    /// or replacing the slot in this `ArrayRef`.
547    /// This is the mirror of [`Self::take_slot_unchecked`].
548    ///
549    /// # Safety
550    /// The replacement must have the same logical dtype and length as the taken slot, and this
551    /// must only be used for physical rewrites.
552    pub(crate) unsafe fn put_slot_unchecked(
553        mut self,
554        slot_idx: usize,
555        replacement: ArrayRef,
556    ) -> VortexResult<ArrayRef> {
557        if let Some(inner) = Arc::get_mut(&mut self.0) {
558            inner.slots[slot_idx] = Some(replacement);
559            return Ok(self);
560        }
561
562        let mut slots: ArraySlots = self.slots().iter().cloned().collect();
563        slots[slot_idx] = Some(replacement);
564        self.0.data.with_slots(&self, slots)
565    }
566
567    /// Returns a new array with the provided slots.
568    ///
569    /// This is only valid for physical rewrites: slot count, presence, logical `DType`, and
570    /// logical `len` must remain unchanged.
571    ///
572    /// # Safety
573    ///
574    /// If this returns `Ok`, the caller must guarantee that each replacement slot represents the
575    /// same logical values as the original slot. Only physical representation may change. Existing
576    /// parent statistics are preserved and must remain valid.
577    pub unsafe fn with_slots(self, slots: ArraySlots) -> VortexResult<ArrayRef> {
578        let old_slots = self.slots();
579        vortex_ensure!(
580            old_slots.len() == slots.len(),
581            "slot count changed from {} to {} during physical rewrite",
582            old_slots.len(),
583            slots.len()
584        );
585        for (idx, (old_slot, new_slot)) in old_slots.iter().zip(slots.iter()).enumerate() {
586            vortex_ensure!(
587                old_slot.is_some() == new_slot.is_some(),
588                "slot {} presence changed during physical rewrite",
589                idx
590            );
591            if let (Some(old_slot), Some(new_slot)) = (old_slot.as_ref(), new_slot.as_ref()) {
592                vortex_ensure!(
593                    old_slot.dtype() == new_slot.dtype(),
594                    "slot {} dtype changed from {} to {} during physical rewrite",
595                    idx,
596                    old_slot.dtype(),
597                    new_slot.dtype()
598                );
599                vortex_ensure!(
600                    old_slot.len() == new_slot.len(),
601                    "slot {} len changed from {} to {} during physical rewrite",
602                    idx,
603                    old_slot.len(),
604                    new_slot.len()
605                );
606            }
607        }
608        self.0.data.with_slots(&self, slots)
609    }
610
611    /// Returns a new array with the provided top-level buffer handles.
612    ///
613    /// This is only valid for physical rewrites: buffer count, logical `DType`, logical `len`, and
614    /// child slots must remain unchanged. Encoding-specific validation checks buffer shape,
615    /// alignment, and metadata consistency.
616    ///
617    /// # Safety
618    ///
619    /// If this returns `Ok`, the caller must guarantee that the replacement buffers represent the
620    /// same logical values as the original buffers. Only the buffer handle implementation,
621    /// placement, or backing storage may change. Existing statistics are preserved and must remain
622    /// valid.
623    pub unsafe fn with_buffers(
624        self,
625        buffers: impl IntoIterator<Item = BufferHandle>,
626    ) -> VortexResult<ArrayRef> {
627        let buffers = buffers.into_iter().collect::<Vec<_>>();
628        let nbuffers = self.nbuffers();
629        vortex_ensure!(
630            nbuffers == buffers.len(),
631            "buffer count changed from {} to {} during physical rewrite",
632            nbuffers,
633            buffers.len()
634        );
635        for (idx, (old_buffer, new_buffer)) in self
636            .buffer_handles()
637            .into_iter()
638            .zip(buffers.iter())
639            .enumerate()
640        {
641            vortex_ensure!(
642                old_buffer.len() == new_buffer.len(),
643                "buffer {} length changed from {} to {} during physical rewrite",
644                idx,
645                old_buffer.len(),
646                new_buffer.len()
647            );
648        }
649        self.0.data.with_buffers(&self, buffers)
650    }
651
652    pub fn reduce(&self) -> VortexResult<Option<ArrayRef>> {
653        self.0.data.reduce(self)
654    }
655
656    pub fn reduce_parent(
657        &self,
658        parent: &ArrayRef,
659        child_idx: usize,
660    ) -> VortexResult<Option<ArrayRef>> {
661        self.0.data.reduce_parent(self, parent, child_idx)
662    }
663
664    pub(crate) fn execute_encoding(self, ctx: &mut ExecutionCtx) -> VortexResult<ExecutionResult> {
665        let inner = Arc::as_ptr(&self.0);
666        // SAFETY: the Arc outlives the DynArrayData function call
667        unsafe { (&*inner).data.execute(self, ctx) }
668    }
669
670    /// Execute a single encoding step without applying `Done`-result postconditions.
671    ///
672    /// This is for the iterative executor only. It may operate on suspended executor-private
673    /// arrays whose slots temporarily contain `None`, so the executor itself must interpret
674    /// `Done`, enforce any `len`/`dtype` invariants, and transfer statistics.
675    pub(crate) fn execute_encoding_unchecked(
676        self,
677        ctx: &mut ExecutionCtx,
678    ) -> VortexResult<ExecutionResult> {
679        let inner = Arc::as_ptr(&self.0);
680        // SAFETY: `inner` points at the allocation owned by `self.0`. `self` stays alive for the
681        // duration of the call, so the pointee remains valid. Avoiding an extra `Arc` clone here
682        // preserves uniqueness so execute-time metadata cursors can use `Arc::get_mut`.
683        unsafe { (&*inner).data.execute_unchecked(self, ctx) }
684    }
685
686    // ArrayVisitor delegation methods
687
688    /// Returns the children of the array.
689    pub fn children(&self) -> Vec<ArrayRef> {
690        self.0.data.children(self)
691    }
692
693    /// Returns the number of children of the array.
694    pub fn nchildren(&self) -> usize {
695        self.0.data.nchildren(self)
696    }
697
698    /// Returns the nth child of the array without allocating a Vec.
699    pub fn nth_child(&self, idx: usize) -> Option<ArrayRef> {
700        self.0.data.nth_child(self, idx)
701    }
702
703    /// Returns the names of the children of the array.
704    pub fn children_names(&self) -> Vec<String> {
705        self.0.data.children_names(self)
706    }
707
708    /// Returns the array's children with their names.
709    pub fn named_children(&self) -> Vec<(String, ArrayRef)> {
710        self.0.data.named_children(self)
711    }
712
713    /// Returns the data buffers of the array.
714    pub fn buffers(&self) -> Vec<ByteBuffer> {
715        self.0.data.buffers(self)
716    }
717
718    /// Returns the buffer handles of the array.
719    pub fn buffer_handles(&self) -> Vec<BufferHandle> {
720        self.0.data.buffer_handles(self)
721    }
722
723    /// Returns the names of the buffers of the array.
724    pub fn buffer_names(&self) -> Vec<String> {
725        self.0.data.buffer_names(self)
726    }
727
728    /// Returns the array's buffers with their names.
729    pub fn named_buffers(&self) -> Vec<(String, BufferHandle)> {
730        self.0.data.named_buffers(self)
731    }
732
733    /// Returns the number of data buffers of the array.
734    pub fn nbuffers(&self) -> usize {
735        self.0.data.nbuffers(self)
736    }
737
738    /// Returns the slots of the array.
739    pub fn slots(&self) -> &[Option<ArrayRef>] {
740        &self.0.slots
741    }
742
743    /// Returns the name of the slot at the given index.
744    pub fn slot_name(&self, idx: usize) -> String {
745        self.0.data.slot_name(self, idx)
746    }
747
748    /// Formats a human-readable metadata description.
749    pub fn metadata_fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
750        self.0.data.metadata_fmt(f)
751    }
752
753    /// Returns whether all buffers are host-resident.
754    pub fn is_host(&self) -> bool {
755        for array in self.depth_first_traversal() {
756            if !array.buffer_handles().iter().all(BufferHandle::is_on_host) {
757                return false;
758            }
759        }
760        true
761    }
762
763    // ArrayVisitorExt delegation methods
764
765    /// Count the number of buffers encoded by self and all child arrays.
766    pub fn nbuffers_recursive(&self) -> usize {
767        self.children()
768            .iter()
769            .map(|c| c.nbuffers_recursive())
770            .sum::<usize>()
771            + self.nbuffers()
772    }
773
774    /// Depth-first traversal of the array and its children.
775    pub fn depth_first_traversal(&self) -> DepthFirstArrayIterator {
776        DepthFirstArrayIterator {
777            stack: vec![self.clone()],
778        }
779    }
780}
781
782impl IntoArray for ArrayRef {
783    #[inline(always)]
784    fn into_array(self) -> ArrayRef {
785        self
786    }
787}
788
789impl<V: VTable> Matcher for V {
790    type Match<'a> = ArrayView<'a, V>;
791
792    #[inline]
793    fn matches(array: &ArrayRef) -> bool {
794        array.0.data.as_any().is::<ArrayData<V>>()
795    }
796
797    #[inline]
798    fn try_match(array: &'_ ArrayRef) -> Option<ArrayView<'_, V>> {
799        let inner = array.0.data.as_any().downcast_ref::<ArrayData<V>>()?;
800        // # Safety checked by `downcast_ref`.
801        Some(unsafe { ArrayView::new_unchecked(array, &inner.data) })
802    }
803}
vortex_array/array/erased.rs

vortex_array/array/
erased.rs
