Skip to content

Commit 9556b96

Browse files
committed
Keep array registration contracts easy to follow
Signed-off-by: Connor Tsui <[email protected]>
1 parent 4c92dd4 commit 9556b96

3 files changed

Lines changed: 150 additions & 155 deletions

File tree

‎vortex-array/src/array/plugin.rs‎

Lines changed: 8 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -112,17 +112,18 @@ pub trait ArrayPlugin: 'static + Send + Sync {
112112
/// Returns the ID of the in-memory encoding that this plugin writes.
113113
fn id(&self) -> ArrayId;
114114

115-
/// Returns the wire IDs that `deserialize` accepts, oldest to newest.
115+
/// Returns the wire IDs that [`deserialize`](Self::deserialize) accepts, oldest to newest.
116116
///
117-
/// `ArraySession::register` makes this plugin the reader of each ID. An ID can stay in this
118-
/// list after the plugin stops writing it, so that old files stay readable.
117+
/// [`ArraySession::register`](crate::session::ArraySession::register) makes this plugin the
118+
/// reader of each ID. An ID can stay in this list after the plugin stops writing it, so that
119+
/// old files stay readable.
119120
fn read_ids(&self) -> Vec<ArrayId>;
120121

121-
/// Returns the wire IDs that `serialize` may return.
122+
/// Returns the wire IDs that [`serialize`](Self::serialize) may return.
122123
///
123-
/// An ID in this list does not have to be in `read_ids`. A plugin can write its arrays in the
124-
/// wire form of another encoding, and the plugin that owns that form reads it. The node must
125-
/// hold the logical values of the array under the dtype of the array.
124+
/// An ID in this list does not have to be in [`read_ids`](Self::read_ids). A plugin can write
125+
/// its arrays in the wire form of another encoding. The plugin that owns that form reads it.
126+
/// The node must hold the logical values of the array under the dtype of the array.
126127
fn write_ids(&self) -> Vec<ArrayId>;
127128

128129
/// Serialize `array` to its wire representation.

‎vortex-array/src/session/mod.rs‎

Lines changed: 7 additions & 148 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,12 @@
11
// SPDX-License-Identifier: Apache-2.0
22
// SPDX-FileCopyrightText: Copyright the Vortex contributors
33

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+
410
use std::any::Any;
511
use std::sync::Arc;
612

@@ -156,151 +162,4 @@ pub trait ArraySessionExt: SessionExt {
156162
impl<S: SessionExt> ArraySessionExt for S {}
157163

158164
#[cfg(test)]
159-
mod tests {
160-
use std::sync::Arc;
161-
162-
use rstest::rstest;
163-
use vortex_error::VortexResult;
164-
use vortex_error::vortex_bail;
165-
use vortex_session::VortexSession;
166-
use vortex_session::registry::Id;
167-
168-
use crate::ArrayDeserialization;
169-
use crate::ArrayId;
170-
use crate::ArrayPlugin;
171-
use crate::ArrayRef;
172-
use crate::ArraySerialization;
173-
use crate::ArrayVTable;
174-
use crate::IntoArray;
175-
use crate::arrays::Bool;
176-
use crate::arrays::Primitive;
177-
use crate::arrays::PrimitiveArray;
178-
use crate::session::ArraySession;
179-
use crate::session::ArraySessionExt;
180-
181-
#[test]
182-
fn array_session_default_registers_encodings() {
183-
let session = VortexSession::empty().with::<ArraySession>();
184-
185-
assert!(
186-
session
187-
.arrays()
188-
.registry()
189-
.contains_key(&ArrayVTable::id(&Bool))
190-
);
191-
assert!(
192-
session
193-
.arrays()
194-
.serializer(&ArrayVTable::id(&Bool))
195-
.is_some()
196-
);
197-
}
198-
199-
#[test]
200-
fn empty_array_session_registers_no_encodings() {
201-
let session = VortexSession::empty().with_some(ArraySession::empty());
202-
203-
assert!(
204-
!session
205-
.arrays()
206-
.registry()
207-
.contains_key(&ArrayVTable::id(&Bool))
208-
);
209-
assert!(
210-
session
211-
.arrays()
212-
.serializer(&ArrayVTable::id(&Bool))
213-
.is_none()
214-
);
215-
}
216-
217-
struct WriteOnlyPrimitivePlugin {
218-
serialized_id: ArrayId,
219-
}
220-
221-
impl ArrayPlugin for WriteOnlyPrimitivePlugin {
222-
fn id(&self) -> ArrayId {
223-
ArrayVTable::id(&Primitive)
224-
}
225-
226-
fn read_ids(&self) -> Vec<ArrayId> {
227-
vec![Id::from("vortex.test.read_only")]
228-
}
229-
230-
fn write_ids(&self) -> Vec<ArrayId> {
231-
vec![self.id()]
232-
}
233-
234-
fn serialize(
235-
&self,
236-
array: &ArrayRef,
237-
_session: &VortexSession,
238-
) -> VortexResult<Option<ArraySerialization>> {
239-
Ok(Some(ArraySerialization::from_array(
240-
self.serialized_id,
241-
array,
242-
vec![],
243-
)))
244-
}
245-
246-
fn deserialize(
247-
&self,
248-
_parts: ArrayDeserialization<'_>,
249-
_session: &VortexSession,
250-
) -> VortexResult<ArrayRef> {
251-
vortex_bail!("the registration test does not deserialize nodes")
252-
}
253-
}
254-
255-
#[test]
256-
fn registration_preserves_the_reader_of_a_write_only_id() {
257-
let session = VortexSession::empty().with::<ArraySession>();
258-
let primitive_id = ArrayVTable::id(&Primitive);
259-
let reader = session.arrays().registry().get(&primitive_id).unwrap();
260-
let plugin = WriteOnlyPrimitivePlugin {
261-
serialized_id: primitive_id,
262-
};
263-
let read_id = plugin.read_ids()[0];
264-
session.arrays().register(plugin);
265-
266-
let arrays = session.arrays();
267-
assert!(Arc::ptr_eq(
268-
&arrays.registry().get(&primitive_id).unwrap(),
269-
&reader
270-
));
271-
assert!(Arc::ptr_eq(
272-
&arrays.registry().get(&read_id).unwrap(),
273-
&arrays.serializer(&primitive_id).unwrap(),
274-
));
275-
}
276-
277-
#[rstest]
278-
#[case::write_only(ArrayVTable::id(&Primitive), true)]
279-
#[case::read_only(Id::from("vortex.test.read_only"), false)]
280-
#[case::undeclared(Id::from("vortex.test.undeclared"), false)]
281-
fn serialization_checks_only_write_ids(
282-
#[case] serialized_id: ArrayId,
283-
#[case] accepted: bool,
284-
) -> VortexResult<()> {
285-
let session = VortexSession::empty().with_some(ArraySession::empty());
286-
session
287-
.arrays()
288-
.register(WriteOnlyPrimitivePlugin { serialized_id });
289-
let array = PrimitiveArray::from_iter([1i32, 2, 3]).into_array();
290-
291-
let result = session.array_serialize(&array);
292-
if accepted {
293-
assert_eq!(result?.unwrap().serialized_id, serialized_id);
294-
assert!(!session.arrays().registry().contains_key(&serialized_id));
295-
} else {
296-
let error = result.expect_err("only declared write IDs may be returned");
297-
assert!(
298-
error
299-
.to_string()
300-
.contains("produced undeclared serialized ID")
301-
);
302-
}
303-
304-
Ok(())
305-
}
306-
}
165+
mod tests;

‎vortex-array/src/session/tests.rs‎

Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
// SPDX-License-Identifier: Apache-2.0
2+
// SPDX-FileCopyrightText: Copyright the Vortex contributors
3+
4+
//! Registration and serialization contracts for independent read and write IDs.
5+
6+
use std::sync::Arc;
7+
8+
use rstest::rstest;
9+
use vortex_error::VortexResult;
10+
use vortex_error::vortex_bail;
11+
use vortex_session::VortexSession;
12+
use vortex_session::registry::Id;
13+
14+
use crate::ArrayDeserialization;
15+
use crate::ArrayId;
16+
use crate::ArrayPlugin;
17+
use crate::ArrayRef;
18+
use crate::ArraySerialization;
19+
use crate::ArrayVTable;
20+
use crate::IntoArray;
21+
use crate::arrays::Bool;
22+
use crate::arrays::Primitive;
23+
use crate::arrays::PrimitiveArray;
24+
use crate::session::ArraySession;
25+
use crate::session::ArraySessionExt;
26+
27+
struct WriteOnlyPrimitivePlugin {
28+
serialized_id: ArrayId,
29+
}
30+
31+
impl ArrayPlugin for WriteOnlyPrimitivePlugin {
32+
fn id(&self) -> ArrayId {
33+
ArrayVTable::id(&Primitive)
34+
}
35+
36+
fn read_ids(&self) -> Vec<ArrayId> {
37+
vec![Id::from("vortex.test.read_only")]
38+
}
39+
40+
fn write_ids(&self) -> Vec<ArrayId> {
41+
vec![self.id()]
42+
}
43+
44+
fn serialize(
45+
&self,
46+
array: &ArrayRef,
47+
_session: &VortexSession,
48+
) -> VortexResult<Option<ArraySerialization>> {
49+
Ok(Some(ArraySerialization::from_array(
50+
self.serialized_id,
51+
array,
52+
vec![],
53+
)))
54+
}
55+
56+
fn deserialize(
57+
&self,
58+
_parts: ArrayDeserialization<'_>,
59+
_session: &VortexSession,
60+
) -> VortexResult<ArrayRef> {
61+
vortex_bail!("the registration test does not deserialize nodes")
62+
}
63+
}
64+
65+
#[test]
66+
fn array_session_default_registers_encodings() {
67+
let session = VortexSession::empty().with::<ArraySession>();
68+
69+
let id = ArrayVTable::id(&Bool);
70+
71+
assert!(session.arrays().registry().contains_key(&id));
72+
assert!(session.arrays().serializer(&id).is_some());
73+
}
74+
75+
#[test]
76+
fn empty_array_session_registers_no_encodings() {
77+
let session = VortexSession::empty().with_some(ArraySession::empty());
78+
79+
let id = ArrayVTable::id(&Bool);
80+
81+
assert!(!session.arrays().registry().contains_key(&id));
82+
assert!(session.arrays().serializer(&id).is_none());
83+
}
84+
85+
#[test]
86+
fn registration_preserves_the_reader_of_a_write_only_id() {
87+
let session = VortexSession::empty().with::<ArraySession>();
88+
let primitive_id = ArrayVTable::id(&Primitive);
89+
let reader = session.arrays().registry().get(&primitive_id).unwrap();
90+
let plugin = WriteOnlyPrimitivePlugin {
91+
serialized_id: primitive_id,
92+
};
93+
let read_id = plugin.read_ids()[0];
94+
session.arrays().register(plugin);
95+
96+
let arrays = session.arrays();
97+
assert!(Arc::ptr_eq(
98+
&arrays.registry().get(&primitive_id).unwrap(),
99+
&reader
100+
));
101+
assert!(Arc::ptr_eq(
102+
&arrays.registry().get(&read_id).unwrap(),
103+
&arrays.serializer(&primitive_id).unwrap(),
104+
));
105+
}
106+
107+
#[rstest]
108+
#[case::write_only(ArrayVTable::id(&Primitive), true)]
109+
#[case::read_only(Id::from("vortex.test.read_only"), false)]
110+
#[case::undeclared(Id::from("vortex.test.undeclared"), false)]
111+
fn serialization_checks_only_write_ids(
112+
#[case] serialized_id: ArrayId,
113+
#[case] accepted: bool,
114+
) -> VortexResult<()> {
115+
let session = VortexSession::empty().with_some(ArraySession::empty());
116+
session
117+
.arrays()
118+
.register(WriteOnlyPrimitivePlugin { serialized_id });
119+
let array = PrimitiveArray::from_iter([1i32, 2, 3]).into_array();
120+
121+
let result = session.array_serialize(&array);
122+
if accepted {
123+
assert_eq!(result?.unwrap().serialized_id, serialized_id);
124+
assert!(!session.arrays().registry().contains_key(&serialized_id));
125+
} else {
126+
let error = result.expect_err("only declared write IDs may be returned");
127+
assert!(
128+
error
129+
.to_string()
130+
.contains("produced undeclared serialized ID")
131+
);
132+
}
133+
134+
Ok(())
135+
}

0 commit comments

Comments
 (0)