Skip to main content

vortex_array/session/
mod.rs

1// SPDX-License-Identifier: Apache-2.0
2// SPDX-FileCopyrightText: Copyright the Vortex contributors
3
4//! Session registries for array readers and writers.
5//!
6//! Writers are keyed by in-memory encoding IDs, while readers are keyed by wire IDs. Keeping the
7//! registries separate lets a writer reuse another encoding's wire form without replacing its
8//! reader.
9
10use std::any::Any;
11use std::sync::Arc;
12
13use vortex_error::VortexResult;
14use vortex_error::vortex_bail;
15use vortex_error::vortex_ensure;
16use vortex_session::ArcSwapMap;
17use vortex_session::SessionExt;
18use vortex_session::SessionGuard;
19use vortex_session::SessionVar;
20use vortex_session::registry::Id;
21
22use crate::ArrayRef;
23use crate::array::ArrayId;
24use crate::array::ArrayPlugin;
25use crate::array::ArrayPluginRef;
26use crate::array::ArraySerialization;
27use crate::arrays::Bool;
28use crate::arrays::Chunked;
29use crate::arrays::Constant;
30use crate::arrays::Dict;
31use crate::arrays::Extension;
32use crate::arrays::FixedSizeList;
33use crate::arrays::List;
34use crate::arrays::ListView;
35use crate::arrays::Map;
36use crate::arrays::Masked;
37use crate::arrays::Null;
38use crate::arrays::PiecewiseSequence;
39use crate::arrays::Primitive;
40use crate::arrays::RunEnd;
41use crate::arrays::Struct;
42use crate::arrays::Union;
43use crate::arrays::VarBin;
44use crate::arrays::VarBinView;
45use crate::arrays::Variant;
46use crate::arrays::decimal::DecimalPlugin;
47use crate::arrays::widen::WidenPlugin;
48
49/// Registry of array encodings.
50pub type ArrayRegistry = ArcSwapMap<Id, ArrayPluginRef>;
51
52#[derive(Clone, Debug)]
53pub struct ArraySession {
54    /// Deserializers keyed by the array ID found on the wire.
55    registry: ArrayRegistry,
56    /// Serializers keyed by the in-memory array encoding ID.
57    serializers: ArrayRegistry,
58}
59
60impl ArraySession {
61    pub fn empty() -> ArraySession {
62        Self {
63            registry: ArrayRegistry::default(),
64            serializers: ArrayRegistry::default(),
65        }
66    }
67
68    pub fn registry(&self) -> &ArrayRegistry {
69        &self.registry
70    }
71
72    /// Register an in-memory array writer and its declared wire readers.
73    ///
74    /// This replaces any serializer with the same in-memory ID and any deserializer registered
75    /// under one of [`ArrayPlugin::read_ids`].
76    pub fn register<P: ArrayPlugin>(&self, plugin: P) {
77        let plugin = Arc::new(plugin) as ArrayPluginRef;
78        self.serializers.insert(plugin.id(), Arc::clone(&plugin));
79        for serialized_id in plugin.read_ids() {
80            self.registry.insert(serialized_id, Arc::clone(&plugin));
81        }
82    }
83
84    fn serializer(&self, id: &ArrayId) -> Option<ArrayPluginRef> {
85        self.serializers.get(id)
86    }
87}
88
89impl Default for ArraySession {
90    fn default() -> Self {
91        let this = ArraySession {
92            registry: ArrayRegistry::default(),
93            serializers: ArrayRegistry::default(),
94        };
95
96        // Register the canonical encodings.
97        this.register(Null);
98        this.register(Bool);
99        this.register(Primitive);
100        this.register(DecimalPlugin);
101        this.register(VarBinView);
102        this.register(ListView);
103        this.register(Map);
104        this.register(FixedSizeList);
105        this.register(Struct);
106        this.register(Union);
107        this.register(Variant);
108        this.register(Extension);
109
110        // Register the utility encodings.
111        this.register(Chunked);
112        this.register(Constant);
113        this.register(Dict);
114        this.register(List);
115        this.register(Masked);
116        this.register(PiecewiseSequence);
117        this.register(RunEnd);
118        this.register(VarBin);
119        this.register(WidenPlugin);
120
121        this
122    }
123}
124
125impl SessionVar for ArraySession {
126    fn as_any(&self) -> &dyn Any {
127        self
128    }
129
130    fn as_any_mut(&mut self) -> &mut dyn Any {
131        self
132    }
133}
134
135/// Session data for Vortex arrays.
136pub trait ArraySessionExt: SessionExt {
137    /// Returns the array encoding registry.
138    fn arrays(&self) -> SessionGuard<'_, ArraySession> {
139        self.get::<ArraySession>()
140    }
141
142    /// Serialize an array using a plugin from the registry.
143    fn array_serialize(&self, array: &ArrayRef) -> VortexResult<Option<ArraySerialization>> {
144        let Some(plugin) = self.arrays().serializer(&array.encoding_id()) else {
145            vortex_bail!(
146                "Array {} is not registered for serialization",
147                array.encoding_id()
148            );
149        };
150
151        let Some(serialization) = plugin.serialize(array, &self.session())? else {
152            return Ok(None);
153        };
154        vortex_ensure!(
155            plugin.write_ids().contains(&serialization.serialized_id),
156            "array serializer {} produced undeclared serialized ID {}",
157            array.encoding_id(),
158            serialization.serialized_id,
159        );
160        Ok(Some(serialization))
161    }
162}
163
164impl<S: SessionExt> ArraySessionExt for S {}
165
166#[cfg(test)]
167mod tests;