vortex_layout/
encoding.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4use std::any::Any;
5use std::fmt::Debug;
6use std::fmt::Display;
7use std::fmt::Formatter;
8
9use arcref::ArcRef;
10use vortex_array::DeserializeMetadata;
11use vortex_array::dtype::DType;
12use vortex_error::VortexExpect;
13use vortex_error::VortexResult;
14use vortex_session::VortexSession;
15use vortex_session::registry::ReadContext;
16
17use crate::LayoutId;
18use crate::LayoutRef;
19use crate::VTable;
20use crate::children::LayoutChildren;
21use crate::segments::SegmentId;
22
23/// Backwards-compatible name for a layout ID.
24pub type LayoutEncodingId = LayoutId;
25/// Shared reference to a registered layout-vtable plugin.
26pub type LayoutVTableRef = ArcRef<dyn LayoutVTablePlugin>;
27/// Backwards-compatible name for a layout-vtable reference.
28pub type LayoutEncodingRef = LayoutVTableRef;
29
30/// Common fields available while deserializing layout-specific data.
31pub struct LayoutDeserializeArgs<'a> {
32    /// Session used to resolve plugin-owned metadata.
33    pub session: &'a VortexSession,
34    /// Array read context referenced by serialized array metadata.
35    pub array_read_ctx: &'a ReadContext,
36    /// Logical dtype of this layout.
37    pub dtype: &'a DType,
38    /// Number of rows in this layout.
39    pub row_count: u64,
40    /// Directly referenced segments.
41    pub segment_ids: Vec<SegmentId>,
42    /// Lazy child access.
43    pub children: &'a dyn LayoutChildren,
44}
45
46/// Context shared while recursively deserializing layouts.
47pub struct LayoutBuildContext<'a> {
48    /// Session used to resolve plugin-owned metadata.
49    pub session: &'a VortexSession,
50    /// Array read context referenced by serialized array metadata.
51    pub array_read_ctx: &'a ReadContext,
52}
53
54/// Object-safe plugin registered for a layout ID.
55pub trait LayoutVTablePlugin: 'static + Send + Sync + Debug {
56    /// Returns this plugin as [`Any`].
57    fn as_any(&self) -> &dyn Any;
58    /// Returns the globally unique layout ID.
59    fn id(&self) -> LayoutEncodingId;
60    /// Deserializes a layout node.
61    fn build(
62        &self,
63        dtype: &DType,
64        row_count: u64,
65        metadata: &[u8],
66        segment_ids: Vec<SegmentId>,
67        children: &dyn LayoutChildren,
68        build_ctx: &LayoutBuildContext<'_>,
69    ) -> VortexResult<LayoutRef>;
70}
71
72/// Backwards-compatible name for the object-safe layout-vtable plugin.
73pub use LayoutVTablePlugin as LayoutEncoding;
74
75impl<V: VTable> LayoutVTablePlugin for V {
76    fn as_any(&self) -> &dyn Any {
77        self
78    }
79
80    fn id(&self) -> LayoutEncodingId {
81        VTable::id(self)
82    }
83
84    fn build(
85        &self,
86        dtype: &DType,
87        row_count: u64,
88        metadata: &[u8],
89        segment_ids: Vec<SegmentId>,
90        children: &dyn LayoutChildren,
91        build_ctx: &LayoutBuildContext<'_>,
92    ) -> VortexResult<LayoutRef> {
93        let metadata = <V::Metadata as DeserializeMetadata>::deserialize(metadata)?;
94        Ok(V::build(
95            self,
96            dtype,
97            row_count,
98            &metadata,
99            segment_ids,
100            children,
101            build_ctx,
102        )?
103        .into_layout())
104    }
105}
106
107impl Display for dyn LayoutVTablePlugin + '_ {
108    fn fmt(&self, f: &mut Formatter<'_>) -> std::fmt::Result {
109        write!(f, "{}", self.id())
110    }
111}
112
113impl PartialEq for dyn LayoutVTablePlugin + '_ {
114    fn eq(&self, other: &Self) -> bool {
115        self.id() == other.id()
116    }
117}
118
119impl Eq for dyn LayoutVTablePlugin + '_ {}
120
121impl dyn LayoutVTablePlugin + '_ {
122    /// Returns whether this plugin is vtable `V`.
123    pub fn is<V: VTable>(&self) -> bool {
124        self.as_opt::<V>().is_some()
125    }
126
127    /// Downcasts this plugin to vtable `V`.
128    pub fn as_<V: VTable>(&self) -> &V {
129        self.as_opt::<V>()
130            .vortex_expect("layout encoding type mismatch")
131    }
132
133    /// Attempts to downcast this plugin to vtable `V`.
134    pub fn as_opt<V: VTable>(&self) -> Option<&V> {
135        self.as_any().downcast_ref()
136    }
137}
vortex_layout/encoding.rs

vortex_layout/
encoding.rs
